The RED interchange API connects systems with the electronic patient record (ePA). It provides features to check if a patient has an electronic record and if so allows to upload data to the patient record.

Every patient is entitled to a personal electronic health record (elektronische Patientenakte ePA). The electronic health record is provided by the patients health insurance organization. Physicians, pharmacies and other health providers shall be able to send documents to and read documents from the electronic health record which therefore acts as a central data exchange hub.

Access to the electronic health record is managed by the patient using a special application (Frontend des Versicherten). There are two ways of granting access 

  • ad-hoc access: the health provider (e.g. a physician) must be connected to the Telematik-Infrastruktur and the patients smartcard (elektronische Gesundheitskarte) must be placed in a card terminal connected to the health providers system. The health provider then may request ad-hoc access, the patient confirms the request and allows access by entering his personal PIN to the card terminal. This process is not feasible for systems without access to the patient smartcard
  • regular access: the patient uses a feature in his Frontend des Versicherten application to select a health provider and grant access. For a system without access to the patient smartcard (e.g. DIGA) this is the only way to get access to the patient record.

Check record existence and access

If a system wants to use an electronic health record record it may use this request to

  • check if the patient has a record provided by an organization (identified by its HomeCommunityID)
  • check if the patient has granted access to the system.

This check is optional; RED will check the status every time a document is sent to the ePA. It is recommended to execute this request only once before the first document is sent. 

The patient identifier (Versichertennummer der eGK) must be provided as parameter patient.

GET request to request ePA status
{{baseURL}}/{{tenant}}/TI?action=$getepastatus&patient=X110542925

See RED Interchange API - Postman Collection - 0350 - ePA Patient Status


If sucessfull the request returns a http status 201 with an XML object containing status for the homeCommunity ID (a health record was provided for this patient) and for authorization of the system identified by its SMC-B. If no person identification was provided the request returs a status 404.

<result>
    <homeCommunity>
        <id>urn:oid:1.2.276.0.76.3.1.466.2.1.3.90.1</id>
        <status>OK</status>
    </homeCommunity>
    <authorizationState>
        <status>OK</status>
    </authorizationState>
</result>

Send a document to the patients electronic health record (non-DiGA)

Data is sent to the electronic health record using a POST requestThe request body must include a valid FHIR bundle with a patient item and a document reference containing the data. 

  • The patient item must reference the unique patient identifier (Versichertennummer)
  • The sending system identifies itself by its Telematik-ID. RED ensures connection to Telematik-Infrastruktur and access to the identifying SMC-B.
  • Data may be sent to the electronic patient record as PDF or XML (e.g. as medical information object MIO). The Frontend des Versicherten application however may not be able to display all XML-files in a meaningful way.
  • The data is handed over as a base64 string
  • Additional meta data is may be sent to describe the document in the electronic health record (see details below)
  • A successful request will return a http status code 201. If an error has occured the status code is 204 with a xml error description 


POST request to send new data to an electronic health record
{{baseURL}}/{{tenant}}/Bundle?action=$createepa

Example: this POST requests sends data to the electronic patient record of the patient referenced in the FHIR bundle


In some cases more than one SMC-B is used to distinguish different sending systems. For this the SMC-B may be attributed with a name (in Terminal setup). The name of the SMC-B to use for the request must be added to the request parameters.

POST request to send new data to an electronic health record
{{baseURL}}/{{tenant}}/Bundle?action=$createepa&cardname=DigaBlue


Send a document to the patients electronic health record as a DiGA

Data is sent to the electronic health record using a POST request. The request body must include a valid FHIR bundle with a patient item and a document reference containing the data. Meta data for document description are not needed as all DiGA documents use a standardized meta data set. RED will automatically add the meta data to the document if the request contains the action "creatediga".


POST request to send new data to an electronic health record as a DiGA
{{baseURL}}/{{tenant}}/Bundle?action=$creatediga

Example: this POST requests sends data to the electronic patient record of the patient referenced in the FHIR bundle as a DiGA


The sending DiGA is identified by its SMC-B. If data is to be sent for several DiGAs each DiGA needs its own named SMC-B (naming in RED terminal setup). The name of the SMC-B to use for the request must be added to the request parameters.

POST request to send new data to an electronic health record
{{baseURL}}/{{tenant}}/Bundle?action=$creatediga&cardname=DigaBlue


Update documents in ePA

Each document is marked with a unique ID (DocumentEntry.entryUUID). This ID determines if the ePA treats the data received as a new document (new UUID) or an update for an existing document (UUID of the original document to be replaced). The UUID is created by RED. RED stores the UUID of each processed document and if a document is to be updated, place the correct UUID in the bundle.

Whether a document is a new or an update for an existing document is determined by you. The header of each document bundle contains an ID (Bundle.id) and a version number (Bundle.meta.versionId):

<Bundle xmlns="http://hl7.org/fhir">
  <id value="10000"/>
  <meta>
    <versionId value="1"/>
    <lastUpdated value="2024-04-14T00:00:00+00:00"/>
    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Bundle_Patientenakte|1.2.0"/>
  </meta>
  <type value="history"/>
  <entry>
...


A new document is marked by an individual document ID (format determined by you) and versionId 1. An update must contain the same id and a versionId larger than 1.

<Bundle xmlns="http://hl7.org/fhir">
  <id value="10000"/>
  <meta>
    <versionId value="2"/>
    <lastUpdated value="2024-04-17T00:00:00+00:00"/>
    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Bundle_Patientenakte|1.2.0"/>
  </meta>
  <type value="history"/>
  <entry>
...


FHIR Bundles

The request body contains two entries - an entry with patient identification and the entry with the document to be sent.

<Bundle xmlns="http://hl7.org/fhir">
	<id and bundle meta data>
	<entry>
		<resource>
			<Patient>
				<id> // is the patient identifier used by the sending system. It is not transmitted to the health record or used to identify the patient in other ways!
				<meta>
				<identifier>
					<value> // is the unique patient identifier (Versichertennummer). This is required to identify the right patient.
				</identifier>
				<name>
			</Patient>
		</resource>
	</entry>
	<entry>
		<resource>
			<DocumentReference>
				<identifier>
				<content>
					<attachment>
						<contentType> // type of document (attachment/pdf or attachment/xml)
						<extension> // optional set with meta information. The value sets are derived from the HL7 definition: https://wiki.hl7.de/index.php?title=IG:Value_Sets_f%C3%BCr_XDS
						<title> // document title for display in patient ePA
						<creation> // date for display and sorting in patient ePA
					</attachment>
			</DocumentReference>
		</reference>
	</entry>
</Bundle>
		


<Bundle xmlns="http://hl7.org/fhir">
    <id value="10000"/>
    <meta>
        <versionId value="1"/>
        <lastUpdated value="2024-01-16T00:00:00+00:00"/>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Bundle_Patientenakte|1.2.0"/>
    </meta>
    <type value="history"/>
    <entry>
        <fullUrl value="http://test.local/fhir/Patient/24325"/>
        <resource>
            <Patient>
                <id value="24325"/>
                <meta>
                    <versionId value="1"/>
                    <lastUpdated value="2024-01-16T00:00:00+00:00"/>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Patient|1.2.0"/>
                </meta>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://fhir.de/CodeSystem/identifier-type-de-basis"/>
                            <code value="GKV"/>
                        </coding>
                    </type>
                    <system value="http://fhir.de/NamingSystem/gkv/kvid-10"/>
                    <value value="X110542925"/>
                </identifier>
                <name>
                    <use value="official"/>
                    <text value="Hillary Steffi Gräfin Schölz"/>
                    <family value="Gräfin Schölz">
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-prefix">
                            <valueString value="Gräfin"/>
                        </extension>
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-name">
                            <valueString value="Schölz"/>
                        </extension>
                    </family>
                    <given value="Hillary Steffi"/>
                </name>
                <gender value="female"/>
                <birthDate value="1972-03-04"/>
            </Patient>
        </resource>
    </entry>
    <entry>
        <resource>
            <DocumentReference>
                <id value="123456"/>
                <identifier>
                    <type>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlage_Identifiertyp"/>
                            <code value="Bezeichnung"/>
                        </coding>
                    </type>
                </identifier>
                <status value="current"/>
                <type>
                    <coding>
                        <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlagetyp"/>
                        <code value="Sonstige"/>
                    </coding>
                </type>
                <created value="2024-01-16T00:00:00Z"/>
                <description value="Test PDF-Dokument"/>
                <content>
                    <attachment>
                        <extension url="http://fhir.de/classificationScheme/authorRole">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.13"/>
                                <code value="5"/>
                                <text value="durchführendes Gerät"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/classCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.8"/>
                                <code value="BEF"/>
                                <text value="Befundbericht"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/confidentialityCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.10"/>
                                <code value="PN"/>
                                <text value="übliche Vertraulichkeit"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/eventCodeList">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.15"/>
                                <code value="H1"/>
                                <text value="vom Patienten mitgebracht"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/formatCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.1.2.3"/>
                                <code value="urn:ihe:iti:xds:2017:mimeTypeSufficient"/>
                                <text value="Format aus MIME Type ableitbar"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/healthcareFacilityTypeCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.3"/>
                                <code value="PAT"/>
                                <text value="Patient"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/languageCode">
                            <valueCoding>
                                <code value="de-DE"/>
                                <text value="Deutsch"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/practiceSettingCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.5"/>
                                <code value="PAT"/>
                                <text value="Patient"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/typeCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.9"/>
                                <code value="BEFU"/>
                                <text value="Ergebnisse Diagnostik"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/contentTypeCode">
                            <valueCoding>
                                <system value="11"/>
                                <code value="1.3.6.1.4.1.19376.3.276.1.5.12"/>
                                <text value="Monitoring"/>
                            </valueCoding>
                        </extension>
                        <contentType value="application/pdf"/>
                        <url value="Dokument1150.pdf"/>
                        <data value="JVBERi0xLjUKJb/3ov4KNiAwIG...........CjIxNgolJUVPRgo="/>
                        <title value="Test PDF-Dokument"/>
                        <creation value="2024-01-16T00:00:00Z"/>
                    </attachment>
                </content>
            </DocumentReference>
        </resource>
    </entry>
</Bundle>


<Bundle xmlns="http://hl7.org/fhir">
    <id value="10000"/>
    <meta>
        <versionId value="1"/>
        <lastUpdated value="2024-01-16T00:00:00+00:00"/>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Bundle_Patientenakte|1.2.0"/>
    </meta>
    <type value="history"/>
    <entry>
        <fullUrl value="http://test.local/fhir/Patient/24325"/>
        <resource>
            <Patient>
                <id value="24325"/>
                <meta>
                    <versionId value="1"/>
                    <lastUpdated value="2024-01-16T00:00:00+00:00"/>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Patient|1.2.0"/>
                </meta>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://fhir.de/CodeSystem/identifier-type-de-basis"/>
                            <code value="GKV"/>
                        </coding>
                    </type>
                    <system value="http://fhir.de/NamingSystem/gkv/kvid-10"/>
                    <value value="X110542925"/>
                </identifier>
                <name>
                    <use value="official"/>
                    <text value="Hillary Steffi Gräfin Schölz"/>
                    <family value="Gräfin Schölz">
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-prefix">
                            <valueString value="Gräfin"/>
                        </extension>
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-name">
                            <valueString value="Schölz"/>
                        </extension>
                    </family>
                    <given value="Hillary Steffi"/>
                </name>
                <gender value="female"/>
                <birthDate value="1972-03-04"/>
            </Patient>
        </resource>
    </entry>
    <entry>
        <resource>
            <DocumentReference>
                <id value="123456"/>
                <identifier>
                    <type>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlage_Identifiertyp"/>
                            <code value="Bezeichnung"/>
                        </coding>
                    </type>
                </identifier>
                <status value="current"/>
                <type>
                    <coding>
                        <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlagetyp"/>
                        <code value="Sonstige"/>
                    </coding>
                </type>
                <created value="2024-01-16T00:00:00Z"/>
                <description value="Test PDF-Dokument"/>
                <content>
                    <attachment>
                        <extension url="http://fhir.de/classificationScheme/authorRole">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.13"/>
                                <code value="5"/>
                                <text value="durchführendes Gerät"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/classCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.8"/>
                                <code value="BEF"/>
                                <text value="Befundbericht"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/confidentialityCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.10"/>
                                <code value="PN"/>
                                <text value="übliche Vertraulichkeit"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/eventCodeList">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.15"/>
                                <code value="H1"/>
                                <text value="vom Patienten mitgebracht"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/formatCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.1.2.3"/>
                                <code value="urn:ihe:iti:xds:2017:mimeTypeSufficient"/>
                                <text value="Format aus MIME Type ableitbar"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/healthcareFacilityTypeCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.3"/>
                                <code value="PAT"/>
                                <text value="Patient"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/languageCode">
                            <valueCoding>
                                <code value="de-DE"/>
                                <text value="Deutsch"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/practiceSettingCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.5"/>
                                <code value="PAT"/>
                                <text value="Patient"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/typeCode">
                            <valueCoding>
                                <system value="1.3.6.1.4.1.19376.3.276.1.5.9"/>
                                <code value="BEFU"/>
                                <text value="Ergebnisse Diagnostik"/>
                            </valueCoding>
                        </extension>
                        <extension url="http://fhir.de/classificationScheme/contentTypeCode">
                            <valueCoding>
                                <system value="11"/>
                                <code value="1.3.6.1.4.1.19376.3.276.1.5.12"/>
                                <text value="Monitoring"/>
                            </valueCoding>
                        </extension>
                        <contentType value="application/pdf"/>
                        <url value="Dokument1150.pdf"/>
                        <data value="JVBERi0xLjUKJb/3ov4KNi..............jIxNgolJUVPRgo="/>
                        <title value="Test PDF-Dokument"/>
                        <creation value="2024-01-16T00:00:00Z"/>
                    </attachment>
                </content>
            </DocumentReference>
        </resource>
    </entry>
</Bundle>


<Bundle xmlns="http://hl7.org/fhir">
    <id value="10000"/>
    <meta>
        <versionId value="1"/>
        <lastUpdated value="2024-02-24T00:00:00+00:00"/>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Bundle_Patientenakte|1.2.0"/>
    </meta>
    <type value="history"/>
    <entry>
        <fullUrl value="http://test.local/fhir/Patient/24325"/>
        <resource>
            <Patient>
                <id value="24325"/>
                <meta>
                    <versionId value="1"/>
                    <lastUpdated value="2024-02-24T00:00:00+00:00"/>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Patient|1.2.0"/>
                </meta>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://fhir.de/CodeSystem/identifier-type-de-basis"/>
                            <code value="GKV"/>
                        </coding>
                    </type>
                    <system value="http://fhir.de/NamingSystem/gkv/kvid-10"/>
                    <value value="X110542925"/>
                </identifier>
                <name>
                    <use value="official"/>
                    <text value="Hillary Steffi Gräfin Schölz"/>
                    <family value="Gräfin Schölz">
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-prefix">
                            <valueString value="Gräfin"/>
                        </extension>
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-name">
                            <valueString value="Schölz"/>
                        </extension>
                    </family>
                    <given value="Hillary Steffi"/>
                </name>
                <gender value="female"/>
                <birthDate value="1972-03-04"/>
            </Patient>
        </resource>
    </entry>
    <entry>
        <resource>
            <DocumentReference>
                <id value="123456"/>
                <identifier>
                    <type>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlage_Identifiertyp"/>
                            <code value="Bezeichnung"/>
                        </coding>
                    </type>
                </identifier>
                <status value="current"/>
                <type>
                    <coding>
                        <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlagetyp"/>
                        <code value="Sonstige"/>
                    </coding>
                </type>
                <created value="2024-02-24T00:00:00Z"/>
                <description value="DIGA PDF-Dokument"/>
                <content>
                    <attachment>
                        <contentType value="application/pdf"/>
                        <url value="DIGA.pdf"/>
                        <data value="JVBERi0xLjUKJb/3ov4KNiAwIG9iag............olJUVPRgo="/>
                        <title value="DIGA-Dokument 1402 0940"/>
                        <creation value="2024-02-24T00:00:00Z"/>
                    </attachment>
                </content>
            </DocumentReference>
        </resource>
    </entry>
</Bundle>


<Bundle xmlns="http://hl7.org/fhir">
    <id value="10000"/>
    <meta>
        <versionId value="1"/>
        <lastUpdated value="2024-02-24T00:00:00+00:00"/>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Bundle_Patientenakte|1.2.0"/>
    </meta>
    <type value="history"/>
    <entry>
        <fullUrl value="http://test.local/fhir/Patient/24325"/>
        <resource>
            <Patient>
                <id value="24325"/>
                <meta>
                    <versionId value="1"/>
                    <lastUpdated value="2024-02-24T00:00:00+00:00"/>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Patient|1.2.0"/>
                </meta>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://fhir.de/CodeSystem/identifier-type-de-basis"/>
                            <code value="GKV"/>
                        </coding>
                    </type>
                    <system value="http://fhir.de/NamingSystem/gkv/kvid-10"/>
                    <value value="X110542925"/>
                </identifier>
                <name>
                    <use value="official"/>
                    <text value="Hillary Steffi Gräfin Schölz"/>
                    <family value="Gräfin Schölz">
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-prefix">
                            <valueString value="Gräfin"/>
                        </extension>
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-name">
                            <valueString value="Schölz"/>
                        </extension>
                    </family>
                    <given value="Hillary Steffi"/>
                </name>
                <gender value="female"/>
                <birthDate value="1972-03-04"/>
            </Patient>
        </resource>
    </entry>
    <entry>
        <resource>
            <DocumentReference>
                <id value="65397"/>
                <identifier>
                    <type>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlage_Identifiertyp"/>
                            <code value="Bezeichnung"/>
                        </coding>
                    </type>
                </identifier>
                <status value="current"/>
                <type>
                    <coding>
                        <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_AW_Anlagetyp"/>
                        <code value="Sonstige"/>
                    </coding>
                </type>
                <created value="2024-02-24T00:00:00Z"/>
                <description value="Test Dokument-DIGA"/>
                <content>
                    <attachment>
                        <contentType value="application/xml"/>
                        <url value="DIGA1615.xml"/>
                        <data value="PEJ1bmRsZSB4bWxucz0iaHR0...........VyY2U+PC9lbnRyeT48L0J1bmRsZT4="/>
                        <title value="DIGA Praxis 0915"/>
                        <creation value="2024-02-24T00:00:00Z"/>
                    </attachment>
                </content>
            </DocumentReference>
        </resource>
    </entry>
</Bundle>










  • No labels