Perform calculation

Request

Endpoint

POST/v2/calculations

Body

This endpoint expects the below fields to be present in the request body.

The calculation_input field expects a key-value pair object where the key represents the calculation input id and the value is the corresponding value for that calculation input.

To know what inputs a calculation expects, you can call the "get calculation" endpoint. In the response you'll find the calculation_blueprint.input_definition field that describes what calculation input ids the calculation expects. Additionally, you can use our Playground to simulate a calculation and see a simulated calculation input.

Below you can find an example for the PHQ-9 calculation.

json
Copy
01{
02  "calculation_id": "phq_9",
03  "calculation_input": {
04    "PHQ9_Q01": 1,
05    "PHQ9_Q02": 1,
06    "PHQ9_Q03": 1,
07    "PHQ9_Q04": 0,
08    "PHQ9_Q05": 3,
09    "PHQ9_Q06": 2,
10    "PHQ9_Q07": 1,
11    "PHQ9_Q08": 3,
12    "PHQ9_Q09": 0
13  }
14}

Response

HTTP 200

When successful, the API will return a HTTP status code of 200. An array of results is returned because some calculations return multiple "subresults" instead of a single score.

Below you can find an example response of the PHQ-9 calculation:

json
Copy
01{
02  "id": "62b8c0c20e46e700122c5f7e",
03  "calculation_id": "bmi",
04  "timestamp": "2022-06-26T20:25:38.973Z",
05  "results": [
06    {
07      "subresult_id": "PHQ9_SCORE",
08      "label": {
09        "en": "PHQ-9 Score"
10      },
11      "type": "number",
12      "result": 16,
13      "status": "CALCULATED"
14    },
15    {
16      "subresult_id": "PHQ9_INTERPRETATION",
17      "label": {
18        "en": "PHQ-9 Interpretation"
19      },
20      "type": "string",
21      "result": "Moderately severe depression",
22      "status": "CALCULATED"
23    }
24  ]
25}

HTTP 404

When you try to perform a calculation that doesn't exist (based on the calculation_id), the API will return a 404 HTTP status code and the following response:

json
Copy
01{
02  "data": {
03    "error": {
04      "message": "Calculation with id \"nonExistentCalculationId\" could not be found."
05    }
06  }
07}

HTTP 500

When unsuccessful, the API will return a 500 HTTP status.

InvalidInputsError

This error is thrown when you're passing at least 1 invalid value for a given calculation input id.

Request:

json
Copy
01{
02  "calculation_id": "bmi",
03  "calculation_input": {
04    "height": -1, // invalid value based on the calculation's definition
05    "weight": 80
06  }
07}

Response:

json
Copy
01{
02  "data": {
03    "error": {
04      "name": "InvalidInputsError",
05      "message": "bmi could not be calculated because some inputs have invalid values passed.",
06      "invalid_inputs": [
07        {
08          "input_id": "height",
09          "input_type": {
10            "type": "number",
11            "range": {
12              "min": {
13                "value": 20
14              },
15              "max": {
16                "value": 300
17              }
18            }
19          },
20          "passed_answer": -1,
21          "reason": {
22            "en": "-1 does not fall in the expected [20, 300] range.",
23            "nl": "-1 valt niet tussen de verwachte [20, 300] grens."
24          }
25        }
26      ]
27    }
28  }
29}

UnexpectedInputsError

This error is thrown when you're passing at least 1 unexpected calculation input id for a given calculation.

Request:

json
Copy
01{
02  "calculation_id": "bmi",
03  "calculation_input": {
04    "age": 40, // the bmi calculation does not expect this calculation input id
05    "weight": 80
06  }
07}

Response:

json
Copy
01{
02  "data": {
03    "error": {
04      "name": "UnexpectedInputsError",
05      "message": "Unexpected inputs were passed into bmi. Please make sure that the calculation inputs you pass match the calculation blueprint.",
06      "unexpected_inputs": ["age"],
07      "calculation_blueprint": {
08        "input_definition": [
09          {
10            "id": "height",
11            "label": {
12              "nl": "Lengte",
13              "en": "Height",
14              "fr": "Longueur",
15              "de": "Länge"
16            },
17            "input_type": {
18              "type": "number",
19              "range": {
20                "min": {
21                  "value": 20
22                },
23                "max": {
24                  "value": 300
25                }
26              }
27            },
28            "format": "cm"
29          },
30          {
31            "id": "weight",
32            "label": {
33              "nl": "Gewicht",
34              "en": "Weight",
35              "fr": "Poids",
36              "de": "Gewicht"
37            },
38            "input_type": {
39              "type": "number",
40              "range": {
41                "min": {
42                  "value": 10
43                },
44                "max": {
45                  "value": 300
46                }
47              }
48            },
49            "format": "kg"
50          }
51        ],
52        "output_definition": [
53          {
54            "subresult_id": "BMI",
55            "label": {
56              "en": "Body Mass Index"
57            },
58            "unit": {
59              "en": "kg/m2"
60            },
61            "type": "number"
62          }
63        ]
64      }
65    }
66  }
67}

Previous versions

v1

The documentation for the v1 endpoint can be found here. The only change between v1 and v2 is the response format.