API Documentation

Eonum provides a RESTful HTTPS API access to the Casematch platform with JSON responses. Configuration of rules and user settings is done in the browser based front-end. Most API calls are private and hence clients ĥave to authorize themselves. If you have any questions or need help to integrate our platform into your system please send an email to info@eonum.ch.

To test the API on the command line using curl:

export ROOT_URL=https://casematch.eonum.ch/2024

Note: All request query parameters can also be sent encoded in a JSON object when the Content-Type request header is set to "application/json".

Choose a year / SwissDRG version

Via the URL path /:year (e.g. /2024), the API allows you to select the SwissDRG version by its application year to use for your requests. The available years/versions can be retrieved under: /versions.json.

Choose your language

Most API calls provide the parameter locale which can be used to select a language. locale=[de|fr|it|en]

Provided languages:

de	German - fully supported, default and fallback language
fr	French - fully supported
it	Itailan - partially supported. no translations for interface texts and rules
en	English - partially supported. no translations for ICD/CHOP/DRG catalogues and rules.

Authentication

Authentication is required for most API calls. Authentication tokens can be obtained by logging in.

{"error":{"name":"authentication_error","description":"Invalid or expired authentication token."}}

If you receive this error message you usually have to get a new authentication token by logging in. An authentication token can be invalidated due to the following reasons:

Automatic expiration after some hours.
Login invalidates old authentication token and creates a new one.
Logout invalidates the authentication token.
Password or user setting changes invalidate the old token and generate a new one.

Login

URL: api/v1/authentication/login
Method: POST
Login using user name and password. Retrieve an authentication token.

Parameters:

user_name	user name
password	password as set in the web interface

Sample login using curl:

curl --data "user_name=testuser&password=secret" --header "Accept: application/json" "$ROOT_URL/api/v1/authentication/login"

Sample response HTTP 200:

{"username":testuser,"status":"ok","authentication_token":"CQVszsUZ15nBz-Qev7Rr"}

Keep the token around for later use:

export TOKEN=CQVszsUZ15nBz-Qev7Rr

Use the API with the authentication token

In order to authenticate yourself for API calls that require authentication you have to add the user authentication token as a query string parameter:

curl --header "Accept: application/json" --data "user_token=$TOKEN" "$ROOT_URL/api/v1/statistical_analyses"

Logout

URL: api/v1/authentication/logout
Method: POST
Logout using the authentication token. The token is invalidated and can no longer be used:

Parameters:

user_token

user authentication token.

Sample logout using curl:

curl --data "user_token=$TOKEN" --header "Accept: application/json" "$ROOT_URL/api/v1/authentication/logout"

Sample response HTTP 200:

{status: "ok", msg: "Successfull logout"}

The patient case URL format

Many API calls (all single patient case POST functions) provide the parameter pc which is a description of a patient case with all relevant information for the SwissDRG Grouper . Since 2018 the preferred format for patient cases is the new SwissDRG Batch / URL 2017 format as documented here: SwissDRG Batchgrouper Format 2017 . The URL 2017 format differs from the Batchgrouper 2017 format by the use of different (URL compatible) separators: '_' (underscore) instead of ';' (semicola) for top level column separators, '-' (hyphen) instead of '|' (pipe) for list item separators, '$' (dollar sign) instead of ':' (colon) for structure separators. The new 2017 format includes admission and exit dates and drugs (ATC) codes necessary for the calculation of supplements (Zusatzentgelte) and used as input in some of our prediction models. The same format (URL 2017) can be used when creating links to the WebGUI version of the Casematch platform. (Case analysis : /patient_cases/analyzenew?locale=de ). ALL the characters used in the URL patient case format are allowed in an URI and do not have to be escaped. If the URL format is invalid and cannot be parsed an HTML status 400 with the following response is sent:

{"error":{"name":"parse_error","description":"Illegal patient case URL format"}}

The variables in detail:

case_number - Fallnummer der Fallkostenstatistik: Beliebiger eindeutiger Schlüssel. Bei Import BFS ist dies die Variable 4.6.V01 Fallnummer der Fallkostenstatistik
Datentyp : string
age_years - Alter in Jahren bei Eintritt: BFS Variable 1.1.V03 - Alter in erfüllten Jahren (Eintrittsdatum-Geburtsdatum) bei Spitaleintritt
Datentyp : number
Range: von 0.0 bis 135.0
age_days - Alter in Tagen: Alter bei Eintritt berechnet aus den BFS Variablen 1.2.V01 und 1.1.V02.
Datentyp : number
Range: von 0.0 bis 365.0
sex - Geschlecht: BFS Variable 1.1.V01 (1 -> M, 2 -> W)
Datentyp : string
Possible values: M W U
Value descriptions: männlich weiblich unbekannt
main_diagnosis - Hauptdiagnose: BFS Variable 1.6.V01 - Die Hauptdiagnose ist als derjenige Zustand definiert, der am Ende des Spitalaufenthalts als Diagnose feststeht und der Hauptanlass für die Behandlung und Untersuchung des Patienten war. Sind mehr als ein Zustand aufgeführt, ist derjenige auszuwählen, der (medizinisch gesehen) den grössten Aufwand an Mitteln erforderte. Erfolgte keine Diagnosenstellung, dann ist das Hauptsymptom, der medizi- nisch schwerwiegendste abnorme Befund oder die schwerwiegendste Gesundheitsstörung als Hauptdiagnose auszuwählen. Die Vergabe der Kodes erfolgt nach den Richtlinien des BFS. Die Angabe kann bis zu fünfstellige Kodes umfassen. Entspricht den fünf ersten Stellen der Variable 4.2.V010
Datentyp : code
diagnoses - Alle Diagnosen: Haupt- und Nebendiagnosen
Datentyp : Array Of code
procedures - Prozeduren: BFS Variablen 4.3
Datentyp : Array Of code

Sending BFS data

API call 'rule_based_analysis' - Rule based analysis of a coding of a patient case

Creates a rule based analysis of a coding of a patient case and responds with a JSON representation of the result. The analysis result is not persisted on the server.
URL: api/v1/rule_based_analyses
Method: POST
Example call:

curl --header "Accept: application/json" --data "user_token=$TOKEN&locale=de& pc=AI34221_65_0_0_M__01__00_1_0_I481-Z921-F051_8954-_" "$ROOT_URL/api/v1/rule_based_analyses"

You need to be logged in to access this function.

The resource 'rules_analysis' provides a list of all rules that apply to the provided coding. Rules can also be based on the statistical analysis of the patient case. Hence a combined analysis (rule-based and statistical) based only on this resource can be made. The configuration of all rules is done in the web front end and is not a part of the API. Each rule has an associated unique name, a color, a category name, a level (info, warning, error) and a description. The description may contain HTML markup (currently only links).

Parameters:

locale	language (optional), See here
pc	patient case in the URL format. See here
user_token	user authentication token. See here

Pretty printed sample response:

The response is composed of a list of rules.