Getting started
Welcome to the Platform API documentation for the Medical Guidance Platform (MGP). This API is a core element of Infermedica’s Medical Guidance Platform designed to support patients and healthcare providers in every step of the primary care journey – from symptom to outcome.
The Platform API provides essential functionalities such as user creation, patient information retrieval, survey scheduling, and AI evidence assessment. This documentation offers clear guidelines, reference materials, and practical examples to help you efficiently utilize the API for developing or integrating healthcare applications.
Platform API is currently unavailable in the European Union.
Platform API - a stateful API
Platform API is stateful, which means that its main domain entities (Users, Patients, Surveys) are stored persistently (with sensitive data, like emails and phone numbers, stored for up to 90 days). This capability could, for instance, allow for more streamlined patient health monitoring that’s based on patient data that was defined or deduced in earlier interviews (this could be basic personal data like age or sex, as well as existing medical evidence).
The entities mentioned are regular web resources that follow REST principles, allowing them to be created, read, updated, and deleted assuming that the user has the appropriate access rights.
Instance
Each API instance requires configuration. The instance will be set up by the Infermedica team. Please contact us if you're interested. Instances are regional (an instance can belong to only one region). The European Union (EU) is set as the default region. Other available regions include Australia (AU) and the United States (US).
| Region | Code | URL |
|---|---|---|
| European Union (default) | EU | https://api.infermedica.com |
| Australia | AU | https://api.au.infermedica.com |
| United States | US | https://api.us.infermedica.com |
Product concepts
Platform API consists of three fundamental entities: User, Patient, and Survey, which interact with each other. A survey is composed of two other fundamental entities: Questions and User Answers.
User
A user could be understood figuratively as an account owner, parent, or caregiver that has control over patients. Basic identifiers for a user, aside from a user_id, could include either their email address or phone number. This entity is responsible for keeping data that is non-medical in nature.
Patient
A patient could be identified as any individual - whether that be a child, elderly person, or the end-user - that would like to identify their concerning health symptoms. A patient can be identified by their patient_id, sex, age, health evidence, or dependency on a user. This entity is responsible for keeping data that is medical in nature.
Survey
A survey is a type of health assessment that includes specific sections designed to gather particular health information. Each survey is created for a specific patient and cannot be transferred to another patient. The survey stores basic information such as type, status, expiry date, etc. A survey can have one of three statuses: new, pending, or completed.
Question
Throughout the course of a survey, health data is gathered about the patient by asking the user a series of questions and saving the user answers. Each question can be of a specific type, including:
dependent, sex, age, risk_factors, report_symptoms, symptoms, onset_time_symptoms, travel_regions, suggest, interview, diseases, diseases_list, specialist, specialist_list, hospitalization, hospitalization_list, hospitalization_time, drugs, drugs_answer, allergy, allergy_answer or comment.
Answer
The structure of the answer depends on the question. The question defines the user's possible answer. Each answer can be of specific type including: choice, multiple_choice, number, symptoms, list, text or duration.
Example flow
Platform API’s basic flow is started with the creation of a user. With a user created, you are then able to create a patient. Having a patient entity enables you to create a survey for the patient. The patient will then, through the survey, be asked questions and provide answers. Once enough answers are gathered, our Inference Engine and AI technology is able to provide a meaningful assessment of the data gathered.
Exemplary flows:
An example flow for an Intake survey requires the creation of a user with either an email or phone number. For example, a user with just an email can be created through a POST request to the /users endpoint.
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.net"
}'When a user is successfully created, a response with the HTTP code 201 Created is returned. The user data in the response body will include: id, email, and phone.
{
"id": "158048dc-8e65-457e-8b1e-6de7435cc374",
"email": "user@example.net",
"phone": null
}After a user is created, a patient entity has to be created. A patient is created by making a POST request to the /patients endpoint with user_id in the request body.
curl "https://api.infermedica.com/api/mgp/v1/patients" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"user_id": "158048dc-8e65-457e-8b1e-6de7435cc374"
}'When a patient is successfully created, a response with the HTTP code 201 Created is returned. The patient data in the response body includes: id, user_id, sex, age, evidence, and dependent.
{
"sex": null,
"age": null,
"evidence": null,
"dependent": null,
"user_id": "158048dc-8e65-457e-8b1e-6de7435cc374",
"id": "1c2c73bd-7283-4c6c-9593-83772fa8ae16"
}With both the user and patient entities created, the next step is to create a Intake survey. To create a survey, you need to make a POST request to the /surveys endpoint and pass a patient_id, as well as the type of survey you'd like to create (intake).
curl "https://api.infermedica.com/api/mgp/v1/surveys" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"type": "intake",
"patient_id": "1c2c73bd-7283-4c6c-9593-83772fa8ae16"
}'If the survey was successfully created, a response with the HTTP code 201 Created is returned. The survey data in the response body includes: id, patient_id, notification_date, type, sections, visit_date, visit_reason, expiration_date, specialist, and status.
{
"notification_date": null,
"type": "intake",
"sections": null,
"visit_date": null,
"visit_reason": null,
"expiration_date": null,
"specialist": null,
"id": "61b03107-0cff-475c-adc0-bdaada2dde3e",
"status": "new",
"patient_id": "1c2c73bd-7283-4c6c-9593-83772fa8ae16"
}Once the survey is created, all of the questions that are asked in the survey will need to be answered to have a completed survey. To receive a question, make a GET request to the /questions/current endpoint.
curl "https://api.infermedica.com/api/mgp/v1/surveys/61b03107-0cff-475c-adc0-bdaada2dde3e/questions/current" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"A successful response from the /questions/current endpoint will return a 200 OK HTTP code, with a question in the response body.
{
"id": "dependent",
"index": 0,
"question": {
"text": "Who is the survey for?"
},
"answer_type": "choice",
"meta": {
"answers": [
{
"id": "myself",
"label": "Myself"
},
{
"id": "someone-else",
"label": "Someone else"
}
]
}
}To provide an answer, make a POST request to /questions/current with the answer to the question in the request body.
curl "https://api.infermedica.com/api/mgp/v1/surveys/61b03107-0cff-475c-adc0-bdaada2dde3e/questions/current" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"answer": {
"id": "myself"
}
}'A successful response will return a 200 OK HTTP code, along with the next question, in the response body.
{
"id": "sex",
"index": 1,
"question": {
"text": "What sex was originally listed on your birth certificate?\n[form:someone] What sex was originally listed on [his/her] birth certificate?"
},
"answer_type": "choice",
"meta": {
"answers": [
{
"id": "female",
"label": "Female"
},
{
"id": "male",
"label": "Male"
}
]
}
}For a survey to be completed, all questions need to be answered. When every question from the /questions/current endpoint is answered, you will receive a 204 No Content HTTP code, along with an empty response body.
As a last check, you could verify survey completion by making a GET request to the /surveys/{survey_id} endpoint and replacing the {survey_id} with the specific survey_id you want confirmed.
curl "https://api.infermedica.com/api/mgp/v1/surveys/61b03107-0cff-475c-adc0-bdaada2dde3e" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"In response, you should receive a 200 OK HTTP response with a response body and the status value completed, which indicates a completed survey.
When there are no more questions, you can retrieve our AI evidence assessment by making a GET request to the /surveys endpoint, specifically /surveys/{survey_id}/evidence_assessment. Replace {survey_id} with the specific survey_id you're looking for in the GET request.
curl "https://api.intermedica.com/api/mgp/v1/surveys/61b03107-0cff-475c-adc0-bdaada2dde3e/evidence_assessment" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"A successful response will return a 200 OK HTTP response, with the AI evidence assessment in response body.
{
"conditions": [
{
"id": "c_735",
"name": "Lactose intolerance",
"common_name": "Lactose intolerance",
"probability": 0.7852,
"rating": "strong",
"icd10": [
{
"code": "E73.0"
},
{
"code": "E73.1"
},
{
"code": "E73.8"
},
{
"code": "E73.9"
}
],
"condition_details": null,
"explain": null,
"patient_education": null
},
{
"id": "c_142",
"name": "Irritable bowel syndrome",
"common_name": "Irritable bowel syndrome",
"probability": 0.1381,
"rating": "moderate",
"icd10": [
{
"code": "K58"
}
],
"condition_details": null,
"explain": null,
"patient_education": null
}
],
"triage": {
"level": "self_care",
"description": "The symptoms you have declared may not require medical evaluation and they usually resolve on their own. Sometimes they can be eased with self-care methods. If the symptoms get worse or new symptoms appear, consult a doctor.",
"serious": []
}
}If you would like to get more detailed insights into how the questions were answered, you could make a GET request to the /surveys endpoint: /surveys/{survey_id}/summary. Replace {survey_id} with the survey ID of the survey you'd like the summary for.
curl "https://api.infermedica.com/api/mgp/v1/surveys/61b03107-0cff-475c-adc0-bdaada2dde3e/summary" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"A successful response will return the 200 OK HTTP code, along with a summary of the survey answers in the response body.
{
"type": "intake",
"patient": {
"id": "1c2c73bd-7283-4c6c-9593-83772fa8ae16",
"age": {
"value": 22,
"unit": "year"
},
"sex": "male",
"dependent": false
},
"visit_reasons": [
{
"id": "test-results",
"name": "I want to discuss the test results\n[form:someone] [He/She] wants to discuss [his/her] test results\n[form:underage] I want to discuss [his/her] test results"
}
],
"onset_time_symptoms": {
"id": "more_24h_less_1_week",
"label": "More than 24 hours to 1 week ago"
},
"chronic_diseases": [
{
"id": "c_471",
"name": "Cerebellopontine angle syndrome",
"severity": null
}
],
"specialists": [],
"hospitalizations": [],
"medications": "",
"allergies": "",
"present_symptoms": [
{
"id": "s_1802",
"name": "Abdominal pain, burning or gnawing",
"choice_id": "present",
"seriousness": "normal",
"source": "initial"
},
{
"id": "s_2275",
"name": "Abdominal pain, localized",
"choice_id": "present",
"seriousness": "normal",
"source": ""
},
{
"id": "s_1531",
"name": "Abdominal pain, right lower quadrant",
"choice_id": "present",
"seriousness": "normal",
"source": ""
},
{
"id": "s_1852",
"name": "Abdominal pain, lasting 2 to 7 days",
"choice_id": "present",
"seriousness": "normal",
"source": ""
},
{
"id": "s_1782",
"name": "Abdominal pain, mild",
"choice_id": "present",
"seriousness": "normal",
"source": ""
},
{
"id": "s_1570",
"name": "Gastric symptoms, after lactose ingestion",
"choice_id": "present",
"seriousness": "normal",
"source": ""
},
{
"id": "s_1844",
"name": "Abdominal pain, gradual onset",
"choice_id": "present",
"seriousness": "normal",
"source": ""
},
{
"id": "s_1847",
"name": "Abdominal pain, recurrent",
"choice_id": "present",
"seriousness": "normal",
"source": ""
},
{
"id": "s_309",
"name": "Bloating",
"choice_id": "present",
"seriousness": "normal",
"source": "suggest"
}
],
"absent_symptoms": [
{
"id": "p_380",
"name": "Consumption of foods or drinks that cause bloating",
"choice_id": "absent",
"seriousness": "normal",
"source": ""
},
{
"id": "s_1432",
"name": "Dyspepsia",
"choice_id": "absent",
"seriousness": "normal",
"source": ""
},
{
"id": "s_57",
"name": "Abdominal pain, reduced by defecation or relieving flatulence",
"choice_id": "absent",
"seriousness": "normal",
"source": ""
},
{
"id": "s_2100",
"name": "Fatigue",
"choice_id": "absent",
"seriousness": "normal",
"source": ""
}
],
"risk_factors": [
{
"id": "p_28",
"name": "Smoking cigarettes",
"choice_id": "present",
"seriousness": "normal",
"source": "suggest"
}
],
"additional_comment": ""
}How to access our API?
Contact us (opens in a new tab) and we will prepare an instance for your company, as well as the necessary access information.