Perform calculation

Request

Endpoint

POST/v1/calculations

Body

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

The calculation_input parameter 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.

json
Copy
01{
02  "calculation_id": "bmi",
03  "calculation_input": {
04    "height": 170,
05    "weight": 80
06  }
07}

Response

HTTP 200

When successful, the API will return a HTTP status code of 200 and in the response an array of results. We return an array of results because some calculations return multiple "subresults" instead of a single score. The schema of the response can be found here.

Below you can find an example response of the bmi calculation:

json
Copy
01[
02  {
03    "subresult_id": "BMI",
04    "label": {
05      "en": "Body Mass Index"
06    },
07    "unit": {
08      "en": "kg/m2"
09    },
10    "type": "number",
11    "result": 27.68166089965398,
12    "status": "CALCULATED"
13  }
14]

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}