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://casematch2019.eonum.ch
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 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. The token based authentication is designed in order to ensure that each user can access the API only with one application at a time. 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. (Code proposals : /coding_proposals?locale=de , 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"}}

However the old format is still available. You can find further documentation on the old format and the used variables (still applicable to the new format) and their calculation in the SwissDRG Grouper documentation ( German , French , Italian )


The old / deprecated URL format is defined by the following state chart:

Examples:
AI34221_65_0_0_M_01_00_1_0_I48.10_Z921_-_8954$$20141212_
XY9868098_23_0_0_W_01_00_1_0_A09.9_O091_-_
345897345_24_0_0_M_11_07_3_0_K85.11_-_
345897345_24_0_0_M_11_07_3_0_K85.11_J80_I490_-_889720$B_99B712$$20141215_0017_

Note:

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
adm_weight - Aufnahmegewicht
BFS Variable 2.2.V04 / 4.5.V01
Datentyp : number
Range: von 0.0 bis 99999.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
adm_mode - Aufnahmeart
BFS Variablen 1.2.V03 und 1.2.V02 (Umrechnung gemäss Grouperdokumentation SwissDRG)
Datentyp : string
Possible values: 01 11 06 99
Value descriptions: Normal Verlegt (Aufenthalt länger als 24 Stunden im verlegenden Spital) Verlegt (Aufenthalt kürzer als 24 Stunden im verlegenden Spital) Unbekannt
sep_mode - Entlassart
BFS Variable 1.5.V02 und 1.5.V03 (Umrechnung gemäss SwissDRG Grouperdokumentation)
Datentyp : string
Possible values: 07 06 04 00 99
Value descriptions: Verstorben Verlegt (in anderes Spital) Gegen ärztlichen Rat beendet Normal Unbekannt
los - Verweildauer in Tagen
Berechnung anhand der BFS Variablen 1.5.V01, 1.2.V01 und 1.3.V04
Datentyp : number
Range: von 1.0 bis 99999.0
hmv - Beatmungsdauer in Stunden
BFS 4.4.V01 - Die Dauer der Beatmung wird nach Intensivstation gemäss den Regeln des aktuell gültigen Kodierungshandbuches berechnet. In diesem Feld gibt es keine Angaben zur Art der künstlichen Beatmung.
Datentyp : number
Range: von 0.0 bis 99999.0
pdx - 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 - Nebendiagnosen
BFS Variablen 4.2 - Angabe der wichtigsten Begleitkrankheiten, die mit der Hauptdiagnose im Zusammenhang stehen. Die Auswahl und Reihung soll nach medizinischen Kriterien erfolgen. Eventuelle Kreuz- und Sternkodes werden linear in die Nebendiagnose-Felder gefügt.
Datentyp : Array Of code
procedures - Prozeduren
BFS Variablen 4.3
Datentyp : Array Of code

Sending BFS data

All POST API calls providing the parameter pc alternatively support the retrieval of patient data using the more extensive format used by the BFS / OFS (Bundesamt für Statistik). Using the more detailed BFS format allows for more detailed and extended checks in the rule based analysis. The format is documented here: German or French and Italian.
BFS data is sent using the following parameters. All parameters represent one line (delimited with '|') in a BFS formatted export:

mb MB minimal data set. Required.
md MD data set. Diagnoses and procedures. Optional.
mn MN data set. Newborns. Optional
mp MP data set. Psychiatric cases. Optional
mf MF data set. Case costs. Optional


API call 'statistical_analyses' - Statistical analysis of a coding of a patient case

Creates a statistical analysis of a coding of a patient case and responds with a JSON representation of the result. The result of the analysis is not persisted on the server.
URL: api/v1/statistical_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/statistical_analyses"
You need to be logged in to access this function.

The API call 'analyze' provides the core functionality of Casematch for the analysis of single patient cases. The provided patient case is grouped and analyzed with the statistical model and the user defined rules.

Parameters:
locale language (optional), See here
pc patient case in the URL format. See here
mb, [md, mn, mp, mf] patient case in the BFS format. See here
user_token user authentication token. See here

Pretty printed sample response:


The response is composed of three parts. "patient_case" is an analysis of the input variables as provided in the parameter 'pc'. Each of the input variables consists of its input 'value', the 'likelihood' and the 'color' (RGB color) associated to this likelihood. The likeliood is a value between -1 and +1. The higher the value the more typical the value is in the context of the grouped DRG. Low likelihoods are associated with red, high with green colors.
The second component are the 'grouper_results'. All grouper outputs are stored here:
drg - DRG
Gruppierte DRG
Datentyp : code
mdc - MDC
MDC - Major Diagnostic Category
Datentyp : string
pccl - PCCL
PCCL - Patient Complexity and Comorbidity Level
Datentyp : number
Range: von 0.0 bis 4.0
ecw - Effektives Kostengewicht
Effektives Kostengewicht nach Abzug/Zuschlag aller Ab- und Zuschläge
Datentyp : number
Range: von 0.0 bis 99999.0
partition - Partition
DRG Partition (M -> Medizinisch, A -> Andere, O -> Operativ)
Datentyp : string
Possible values: M O A
case_flag - Abrechnungsstatus

Datentyp : string
Possible values: 01 02 03 04 05
Value descriptions: Normallieger Oberer Outlier Unterer Outler Verlegungsabschlagspflichtig Unbewertete DRG
The third component are the 'analysis_results', all results from the statistical analysis:
stat_drg - Statistische DRG
Wahrscheinlichste DRG gemäss dem statistischen Modell / Klassifikator. Dies ist die DRG mit der grössten Ähnlichkeit zu diesem Fall.
Datentyp : code
rank - Ähnlichkeitsindex
Ähnlichkeitsindex: Rang der gruppierten DRG im berechneten Modell. Ein Rang von 1 bedeutet, dass die gruppierte DRG auch die ähnlichste DRG ist. In diesem Fall stimmen das statistische Modell und die DRG-Gruppierung überein.
Datentyp : number
Range: von -1.0 bis 1000.0
top_ranks - Ähnliche DRGs
Liste der 5 ähnlichsten DRGs gemäss dem statistischen Modell.
Datentyp : Array Of string
likelihood - Ähnlichkeit
Ähnlichkeit dieses Falles zur gruppierten DRG. Berechnet als Zuweisungswahrscheinlichkeit im statistischen Modell. Der Wert liegt zwischen 0 und 1. Die Ähnlichkeitswerte aller DRGs für einen Fall summieren sich auf 1.
Datentyp : number
Range: von 0.0 bis 1.0
model_train_number - Fallzahl für DRG-Modell

Datentyp : number
Range: von 0.0 bis

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
mb, [md, mn, mp, mf] patient case in the BFS format. See here
user_token user authentication token. See here

Pretty printed sample response:


The response is composed of a list of rules.

API call 'coding_proposals' - Propose codes for a patient case

Creates coding proposals for a coding of a patient case and responds with a JSON representation of the resource. The resource is not persisted on the server.
URL: api/v1/coding_proposals
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/coding_proposals"
Example: POST /api/v1/coding_proposals?locale=de&pc=AI34221_65_0_0_M__01__00_1_0_I481-Z921-F051_8954-_
Login required.

The API call 'propose' generates a list of related diagnoses and procedures based on the context of the provided coding (parameter 'pc').

Parameters:
locale language, See here
pc patient case. See here
user_token user authentication token. See here

Pretty printed sample response:


API call 'predictions' - Predict length of stay for a patient case

Predicts the length of stay for a patient case and responds with a JSON representation of the resource. The resource is not persisted on the server.
URL: api/v1/predictions
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/predictions"
Example: POST /api/v1/predictions?locale=de&pc=AI34221_65_0_0_M__01__00_1_0_I481-Z921-F051_8954-_
Login required.

The API call 'predictions' generates a number based on the context of the provided patient case (parameter 'pc').

Parameters:
locale language, See here
pc patient case. See here
user_token user authentication token. See here

Pretty printed sample response: