Create IBRA Case
Description
Creates an IBRA Case from treatment data submitted. This resource also allows upload of multiple IBRA cases in a single request (bulk upload).
Background
The basic idea is to collect all case-related data, including preoperative, operational and postoperative data in the application of the API Service Provider (e.g. an EMR or DHS system), which serves as the 'primary database'.
This treatment data is send to IBRA for the calculation of the surgeon-specific nomogram, an important parameter, which then can be used via the iframe laser treatment planner by the surgeon.
The data can also be viewed and further analysed with the IBRA standalone software (users might require additional login credentials).
This case data is not the same as the 'iframe case', see below, which is used as a data handler only.
URL
POST https://www.zubisoft.com/api/cases
Permission
Standard authentication with public key, hashed private key and user key.
Resource must be enabled for the requesting application (defined by the subscription plan on customer account level).
Parameters
You need to submit an array 'data'. The most commonly used data fields are listed below as an example. A full list of possible data fields is available here.case_id provided
- This is the recommended approach, working with pseudo-anonymized data.
- We suggest you provide a unique case identification number (case_id) with each case, the same you store in your EMR system or DHS.
- If IBRA can find an iframe case with the same case_id, IBRA will get the preoperative and operational data provided with the iframe treatment planner.
- Data provided with the request, e.g. method, will be seen as dominant, and will be used instead of the one from the iframe case (can be used for updates).
- If IBRA can not find an iframe case with the same case_id, IBRA will go ahead and create a new IBRA case with the provide case_id, and a full set of data has to be submitted.
case_id not provided
- A new IBRA case will be created and IBRA will allocated a case id to it (for internal use only).
- The data provided with the request will be stored with the IBRA case.
- This approach enables fully anonymized data handling.
Surgeon-specific nomogram
- The creation of a surgeon-specific nomogram requires preoperative manifest refraction, target refraction, treatment refraction and postoperative manifest refraction.
- When using the iframe treatment planner you will record: preoperative manifest refraction, target refraction and treatment refraction.
- Postoperative manifest refraction can be added with case_id for the IBRA case creation (see example below: JSON Surgeon-specific Nomogram).
Adding patient data
- With the parameter 'addpatients' (Boolean) you can decide wheter the API should automatically generate patients from your data (set to 'true', standard is 'false').
- The following fields are available for the patient record: 'sex', 'pid', 'surname', 'firstname', 'dob', 'street', 'postcode', 'city', 'phone', 'email', 'notes'
- The following fields are the minimal requirement: 'pid', 'surname', 'firstname', 'dob'
- A patient entry is only created for new 'patient ids' (pid) provided. If the pid already exists, the patient does not get created again.
Range and format of data
- Please note the minimum (min) and maximum (max) values for each field in the table below.
- Please note the format: for example visual acuities are in decimal (e.g. 0.8 for 20/25 or 6/7.5), axial lenght and optical zone in mm, pachymetry in micrometer.
- Please note that the age provided with an iframe case (e.g. 43) differs to the DOO format (YYYY-01-01) used for the IBRA case creation.
Rejection
No case will be created if one of the following situation appears:
- A case with the same case ID (cid) already exists (the API returns an array with the cid of all already existing cases; error_code=1).
- The value of a field is outside of the min/max range (the API returns an array with the cid of the affect case(s) and the name of the affected field; error_code=2)
- A successfull case creation response will look like: {"success": true,"casesRejected": []}
JSON examples
- The example contains 2 cases: the first with typical data for a laser treatment (incl. patient data), the second with typical data for an IOL treatment.
- For date fields (DOB and DOO) only the year is submitted in case 2: DOB has date format (YYYY-01-01), and DOO has datetime format (YYYY-01-01 00:00:00).
- Personal identifiers (case_id, pid, surname) are optional and can be removed if needed (HIPPA), as in case 2.
- If personal identifiers are provided, the date of birth (DOB) must be full (YYYY-MM-DD), and not just the year (YYYY-01-01), see case 1.
| Field | Format | Example | Comment | Min | Max |
|---|---|---|---|---|---|
| case_id | Text | Lujh3dg7863 | ID of your case | ||
| eye | text | od (R) | od (R) or os (L) | ||
| doo | date | 2021-08-26 | Date of operation | ||
| anterior_chamber_depth | Float | 3.02 | Depth of the anterior chamber in millimeter preoperatively (from endothelium in phakic IOLs) | 0 | 6 |
| axial_length | Float | 25.34 | Axial length in millimeter | 15 | 39 |
| cdva_pre | Float | 0.2 | (Spectacle/Best) Corrected distance visual acuity in decimal preoperatively (monocular) | 0 | 2 |
| cdva_1m | Float | 0.33 | (Spectacle/Best) Corrected distance visual acuity in decimal at 1 month follow-up (monocular) | 0 | 2 |
| incision_axis | Integer | 91 | Axis (meridian) of the main incision in degrees | 0 | 360 |
| iol | Integer | 80 | Id of an IOL (see resource Devices to get a list) | ||
| iol_axis_preop | Integer | 87 | Intended axis of placement of toric IOLs (preoperative) in degrees | 0 | 180 |
| iol_constant | Float | 119.2 | IOL constant used for calculation of above sphere IOL power (usually SRK/T; but can be a0 of Haigis) | 110 | 130 |
| iol_power_sphere | Float | 22.5 | Spherical power of the intraocular lens (IOL) in diopters | -16 | 44 |
| k_flat_pre | Float | 22.5 | Flatter K-value in diopters preopratively | 20 | 70 |
| k_steep_axis_pre | Float | 95 | Axis of the steeper K-value in degrees preopratively | 0 | 180 |
| k_steep_pre | Float | 1 | ID of the laser. See Resource Devices for IDs. | ||
| laser_excimer | Integer | 3 | ID of excimer laser used for ablation:
|
||
| laser_mode | Text | WFO | Excimer laser mode (e.g. WFO, wavefront guided, T-CAT, tissue saving,...) | ||
| laser_optical_zone | Float | 6.3 | Diameter of the opical zone in millimeter | 1 | 10 |
| laser_treatment_axis | Integer | 85 | Axis of the cylinder of the refractive treatment in degrees | 0 | 180 |
| laser_treatment_cylinder | Float | -1.25 | Cylinder amount of the refractive treatment in diopters | -20 | 20 |
| laser_treatment_sphere | Float | -3.5 | Sphere amount of the refractive treatment in diopters | -25 | 25 |
| manifest_axis_pre | Integer | 90 | Axis of the manifest cylinder (in degrees) preoperatively | 0 | 180 |
| manifest_axis_1m | Integer | 90 | Axis of the manifest cylinder (in degrees) at 1 month follow-up | 0 | 180 |
| manifest_cylinder_pre | Float | -1.5 | Manifest cylinder (subjective refraction in diopters) preoperatively | -20 | 20 |
| manifest_cylinder_1m | Float | -0.5 | Manifest cylinder at 1 month follow-up | -20 | 20 |
| manifest_sphere_pre | Float | -3.75 | Manifest sphere (subjective refraction in diopters) preoperatively | -25 | 25 |
| manifest_sphere_1m | Float | -0.25 | Manifest sphere at 1 month follow-up | -25 | 25 |
| method | String | LASIK | Supported methods for excimer laser:
| ||
| target_sphere | Float | -0.26 | Sphere of the target refraction | -20 | 20 |
| udva_pre | Float | 0.1 | Uncorrected distance visual acuity in decimal preoperatively (monocular) | 0 | 2 |
| udva_1m | Float | 0.4 | Uncorrected distance visual acuity in decimal at 1 month follow-up (monocular) | 0 | 2 |
{
"addpatients": true,
"data": [
{
"case_id": "12311564_v837",
"eye": "od (R)",
"date_operation": "2021-01-01 00:00:00",
"method": "LASIK",
"laser_excimer": 3,
"laser_mode": "WFO",
"intervention": "first",
"laser_optical_zone": 6.5,
"target_sphere": 0,
"target_cylinder": 0,
"pachymetry_central_pre": 548,
"laser_treatment_sphere": -5.5,
"laser_treatment_cylinder": -1.75,
"laser_treatment_axis": 95,
"udva_pre": 0.05,
"udva_1m": 0.63,
"udva_3m": 0.8,
"cdva_pre": 1,
"cdva_1m": 1,
"cdva_3m": 1.25,
"manifest_sphere_pre": -5.75,
"manifest_sphere_1m": 0.5,
"manifest_sphere_3m": 0.25,
"manifest_cylinder_pre": -2,
"manifest_cylinder_1m": -0.75,
"manifest_cylinder_3m": -0.5,
"manifest_axis_pre": 95,
"manifest_axis_1m": 80,
"manifest_axis_3m": 85,
"satisfaction": 5,
"complications_intraop": "none",
"complications_postop": "none",
"pid": "12311564",
"surname": "Every",
"firstname": "Claudianus",
"dob": "1980-11-21",
"sex": "m"
},
{
"eye": "os (L)",
"dob": "1980-01-01",
"date_operation": "2021-01-01 00:00:00",
"method": "Phaco Cat",
"iol": 83,
"iol_power_sphere": 21.5,
"iol_power_cylinder": 2.25,
"iol_constant": 119.3,
"iol_axis_preop": 86,
"target_sphere": -0.18,
"target_cylinder": -0.08,
"incision_axis": 100,
"axial_length": 23.74,
"anterior_chamber_depth": 2.94,
"k_flat_pre": 43.03,
"k_steep_pre": 45.12,
"k_steep_axis_pre": 88,
"k_flat_1m": 43.32,
"k_steep_1m": 45.05,
"k_steep_axis_1m": 83,
"firstday_udva": 0.63,
"udva_pre": 0.05,
"udva_1m": 0.8,
"udva_3m": 1,
"cdva_pre": 0.4,
"cdva_1m": 1,
"cdva_3m": 1.25,
"manifest_sphere_pre": 2.75,
"manifest_sphere_1m": 0.5,
"manifest_sphere_3m": 0.25,
"manifest_cylinder_pre": -2,
"manifest_cylinder_1m": -0.75,
"manifest_cylinder_3m": -0.5,
"manifest_axis_pre": 5,
"manifest_axis_1m": 175,
"manifest_axis_3m": 0,
"satisfaction": 4,
"complications_intraop": "none",
"complications_postop": "none"
}
]
}
curl --location --request POST 'http://localhost/api/cases' \
--header 'Content-Type: application/json' \
--header 'X-Private-Key: cb8379ac2098aa165029e3938a51da0bcecfc008fd6795f401178647f96c5b34' \
--header 'X-Public-Key: emr1_384hf3' \
--header 'X-User-Key: nnPkEbeMU6Jm' \
--data-raw '{
"addpatients": true,
"data": [
{
"case_id": "12311564_v837",
"eye": "od (R)",
"date_operation": "2021-01-01 00:00:00",
"method": "LASIK",
"laser_excimer": 3,
"laser_mode": "WFO",
"intervention": "first",
"laser_optical_zone": 6.5,
"target_sphere": 0,
"target_cylinder": 0,
"pachymetry_central_pre": 548,
"laser_treatment_sphere": -5.5,
"laser_treatment_cylinder": -1.75,
"laser_treatment_axis": 95,
"udva_pre": 0.05,
"udva_1m": 0.63,
"udva_3m": 0.8,
"cdva_pre": 1,
"cdva_1m": 1,
"cdva_3m": 1.25,
"manifest_sphere_pre": -5.75,
"manifest_sphere_1m": 0.5,
"manifest_sphere_3m": 0.25,
"manifest_cylinder_pre": -2,
"manifest_cylinder_1m": -0.75,
"manifest_cylinder_3m": -0.5,
"manifest_axis_pre": 95,
"manifest_axis_1m": 80,
"manifest_axis_3m": 85,
"satisfaction": 0,
"complications_intraop": "none",
"complications_postop": "none",
"pid": "12311564",
"surname": "Every",
"firstname": "Claudianus",
"dob": "1980-11-21",
"sex": "m"
},
{
"case_id": "12311564_v912",
"eye": "os (L)",
"date_operation": "2021-01-01 00:00:00",
"method": "Phaco Cat",
"iol": 83,
"iol_power_sphere": 21.5,
"iol_power_cylinder": 2.25,
"iol_constant": 119.3,
"iol_axis_preop": 86,
"target_sphere": -0.18,
"target_cylinder": -0.08,
"incision_axis": 100,
"axial_length": 23.74,
"anterior_chamber_depth": 2.94,
"k_flat_pre": 43.03,
"k_steep_pre": 45.12,
"k_steep_axis_pre": 88,
"k_flat_1m": 43.32,
"k_steep_1m": 45.05,
"k_steep_axis_1m": 83,
"firstday_udva": 0.63,
"udva_pre": 0.05,
"udva_1m": 0.8,
"udva_3m": 1,
"cdva_pre": 0.4,
"cdva_1m": 1,
"cdva_3m": 1.25,
"manifest_sphere_pre": 2.75,
"manifest_sphere_1m": 0.5,
"manifest_sphere_3m": 0.25,
"manifest_cylinder_pre": -2,
"manifest_cylinder_1m": -0.75,
"manifest_cylinder_3m": -0.5,
"manifest_axis_pre": 5,
"manifest_axis_1m": 175,
"manifest_axis_3m": 0,
"satisfaction": 0,
"complications_intraop": "none",
"complications_postop": "none",
"pid": "12311564",
"surname": "Every",
"firstname": "Claudianus",
"dob": "1980-11-21",
"sex": "m"
}
]
}'
{
"addpatients": false,
"data": [
{
"case_id": "12311564_v837",
"manifest_sphere_1m": 0.25,
"manifest_cylinder_1m": -0.5,
"manifest_axis_1m": 80
}
]
}
Response
The response includes the following values:
| Name | Format | Example | Comment |
|---|---|---|---|
| success | Boolean |
{
"success": true
}
Response of errors
In the situation where one or more cases get rejected the following response appears:
| Name | Format | Example | Comment |
|---|---|---|---|
| case_id | Boolean | 2cc8hd86g | |
| error_code | Boolean | 2 | error_code=1: case already exists
error_code=2: field value outside of allowed range |
| field | Boolean | axial lenght | |
| field_value | Boolean | 235 | |
| min | Boolean | 15 | |
| max | Boolean | 39 |
{
"success": true,
"casesRejected": [
{
"cid": "1trch5qmex",
"error_code": 2,
"error_description": "Field out of range",
"error_field": "manifest_sphere_pre",
"field_value": -30,
"min": -25,
"max": 25
},
{
"cid": "kiegdwe542",
"error_code": 1,
"error_description": "Case already present"
}
]
}