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:

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:

Authentication

Login

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:

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=fr , Case analysis : /patient_cases/analyzenew?locale=fr ). 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:

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 - Clef du cas Numéro du cas dans la statistique des coûts par cas

Au choix
Type de données : string

age_years - Age en années

BFS-medstat: "1.1.V03" BFS Variable 1.1.V03 - Age en années révolues au début du séjour hospitalier (Date de OFS l’admission - date de naissance). Spiges: "alter: Âge lors de l’admission" Âge en années révolues (date d’admission-date de naissance) lors de l’admission à l’hôpital.
Type de données : number
Range: von 0.0 bis 135.0

age_days - Age en jour

BFS-medstat: "age_days" Alter bei Eintritt berechnet aus den BFS Variablen 1.2.V01 und 1.1.V02. Spiges: "alter_u1: Âge en jours des enfants de moins d'un an" Âge à l'entrée en jours. A indiquer pour les enfants âgés de moins d'un an. Le jour d'entrée ne doit pas être compté (calcul : jour d'entrée - anniversaire). L'indication est obligatoire pour le regroupement des données SpiGes selon SwissDRG, TARPSY, ST-Reha et GPPH. Lors du téléchargement sur la plateforme SpiGes, elle est toutefois facultative. Lors du téléchargement, elle est automatiquement complétée.
Type de données : number
Range: von 0.0 bis 365.0

adm_weight - Poids de l'admission

BFS-medstat: "4.5.V01" BFS Variable 2.2.V04 / 4.5.V01 Spiges: "aufnahmegewicht: Poids à l’admission" En grammes, poids à l’admission d’un nourrisson (un enfant de moins de 12 mois). Lorsque la naissance a eu lieu lors de l’hospitalisation en cours, le poids à la naissance (variable Poids de naissance) doit correspondre au poids d’admission de ce champ.
Type de données : number
Range: von 0.0 bis 99999.0

sex - Sexe

BFS-medstat: "1.1.V01" BFS Variable 1.1.V01 (1 -> M, 2 -> W) Spiges: "geschlecht" Sexe de l’individu. Pour les changements de sexe, le sexe à indiquer est celui de l’état civil lors de l’admission à l’hôpital.
Type de données : string
Possible values: M W U
Value descriptions: masculin féminin inconnu

adm_mode - Type d'admission

BFS Variablen 1.2.V03 und 1.2.V02 (Umrechnung gemäss Grouperdokumentation SwissDRG)
Type de données : string
Possible values: 01 11 06 99
Value descriptions: normal transféré (Séjour plus long que 24 heures dans l'hôpital de soins aigus transférant.) transféré (Séjour plus court que 24 heures dans l'hôpital de soins aigus transférant.) inconnu

sep_mode - Type de sortie

BFS Variable 1.5.V02 und 1.5.V03 (Umrechnung gemäss SwissDRG Grouperdokumentation)
Type de données : string
Possible values: 07 06 04 00 99
Value descriptions: décédé transféré (dans un autre hôpital) terminé contre l'avis médical normal inconnu

los - Durée du séjour en jours

Berechnung anhand der BFS Variablen 1.5.V01, 1.2.V01 und 1.3.V04
Type de données : number
Range: von 1.0 bis 99999.0

hmv - Durée de respiration artificielle

BFS-medstat: "4.4.V01" BFS 4.4.V01 - La durée de la ventilation est calculée par l’unité de soins intensifs en suivant les règles du manuel de codage en vigueur. Pas d’information dans ce champ, sur le genre de ventilation artificielle. Spiges: "beatmung: Durée de la ventilation artificielle" En nombre d’heures. La durée de la ventilation est calculée après séjour en unité de soins intensifs, en suivant les règles du manuel de codage en vigueur. Pas d’information dans ce champ sur le genre de ventilation artificielle. Définition reprise de la Société suisse de médecine intensive (SSMI). Les données se trouvent dans la base de la SSMI.
Type de données : number
Range: von 0.0 bis 99999.0

main_diagnosis - Diagnostic principal

BFS Variable 1.6.V01 L’affection principale est définie comme l’affection qui, au terme du traitement, est considérée comme ayant essentiellement justifié le traitement ou les examens prescrits. En présence de plusieurs affections de ce type, on choisira celle qui a entraîné l'engagement des moyens médicaux les plus importants. Si aucun diagnostic n’a été posé, on retiendra comme affection principale le symptôme, le résultat s'écartant le plus de la norme ou le trouble affectant le plus la santé. La codification est effectuée selon les directives de l’OFS. Le code peut compter jusqu'à cinq positions. Correspond aux 5 premières positions de la var. 4.2.V010
Type de données : code

diagnoses - Diagnostics

Diagnostic principal et diagnostics secondaire
Type de données : Array Of code

procedures - Procédures

Variables OFS 4.3
Type de données : 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:

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: 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:
Pretty printed sample response:

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: 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:
Pretty printed sample response:

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: Example: POST /api/v1/coding_proposals?locale=fr&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:
Pretty printed sample response:

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

Predicts the length of stay and scenarios for a patient case in the context of a precoding and responds with a JSON representation of the resource. October 2019: Currently the scenarios / simulations is just a mockup. Integration with the ML backend is planned for Winter 2019/2020. The resource is not persisted on the server.
URL: api/v1/predictions
Method: POST
Example call: Example: POST /api/v1/predictions?locale=fr&pc=AI34221_65_0_0_M__01__00_1_0_I481-Z921-F051_8954-_
Login required.

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

Parameters:
Pretty printed sample response: