API Technical Specifications


The Medal API allows you to perform all the operations that are available on our web client. Medal API is built using REST principles which ensures predictable URLs so writing your applications is easy. This API follows HTTP rules, so a wide range of HTTP clients can be used to interact with the API. Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.


HTTP Request method and Authentication

The API supports HTTP POST & authentication using the combination of a user specific API-key and an algorithm key. This allows you to protect your API URLs on your web server so that only you can access them. You may provide an API-key and an algorithm key by setting headers as shown below.

curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
	"Content-type: application/json","x-api-key:API-KEY",

API using PHP cURL - Example

$url = "";
$input_variables = array(
$content = json_encode($input_variables);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
   "Content-type: application/json", "x-api-key:API-KEY",
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$response = json_decode($json_response, true);

API Response

The API provides results in JSON object containing the algorithm's basic Information, provided inputs, generated output variables & error messages if applicable.

A sample API response is shown as follows:

"algorithm_info": {
	"title": "Guidelines for When to Call Pediatrician About Febrile 
"inputs": {
  "ivar1": "yes","ivar2": 1,"ivar3": "no","ivar4": 38,
  "ivar17": "mild"
  "results": {
  "status": "success",
  "errors": null,
  "outputs": { "ovar1": "yes","ovar2": "yes","ovar3": "3","ovar4": "yes"

As shown in the above sample output, the API will provide the algorithm’s basic info, provided inputs and the algorithm’s output details will be found under the results section, depending upon the status property, i.e. if the status property returns 'success' then its outputs will be given under its 'outputs' property else error messages will be returned through its 'errors' property.

HTTP response codes
Status CodeDescription
400Bad Request. Possibly missing API-key or algorithm key
401Unauthorized/Invalid API-key
500Internal Server Error


medal descover
medal iphone