Surveys
Overview
To allow a user to collect information about a patient, a survey instance must be created. It can be created using the /surveys
endpoint. Each survey is represented by a unique generated ID. Using this ID, it's possible to manage the survey, retrieve the questions
assigned to the survey, etc.
Creating a survey
To create a survey, send a POST request to the /api/mgp/v1/surveys
endpoint.
curl "https://api.infermedica.com/api/mgp/v1/surveys" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"patient_id": "9a6a05c9-a138-467a-b998-ad4e63c53daa",
"type": "intake"
}'
If the request was successful, you will receive a 204 Created
HTTP response and the following object in the response body.
{
"notification_date": null,
"type": "intake",
"sections": null,
"visit_date": null,
"visit_reason": null,
"expiration_date": null,
"specialist": null,
"id": "c7d8d208-3fc1-493a-a260-dc3157bc45e9",
"status": "new",
"patient_id": "9a6a05c9-a138-467a-b998-ad4e63c53daa"
}
Survey create request parameters in body
The following survey parameters can be added to the request parameter body when creating a survey. Our survey creation endpoint validation doesn't suppress additional parameters. However, they won't be saved to the survey entity. The list of all acceptable survey parameters:
type
- required string parameter that defines the type of survey. For Intake, the only acceptable value isintake
sections
- optional list parameter that stores selected sections for survey. Allowed values are:dynamic
,visit_reason
,risk_factors
,chronic_diseases
,specialist
,hospitalization
,allergies
,message_to_doctor
, anddrugs
.specialist
- optional string parameter that can store any value that identifies a recommended specialist.visit_reason
- optional list parameter that stores a list of objects with theid
attribute identifying the reason for a visit, e.g.[{"id": "symptoms"}]
. Possible values for theid
attribute in object include:symptoms
,test_results
,prescription_extension
,follow_up
,other
.visit_date
- optional date parameter that stores the date and time of visit. Acceptable value must be in ISO 8601 format, e.g.2024-06-04T12:16:20.430056
expiration_date
- optional date parameter that stores the date and time of survey expiration. Acceptable value must be in ISO 8601 format, e.g.2024-06-04T12:16:20.430056
notification_date
- optional date paramater that stores the date and time of survey notification date. Acceptable value must be in ISO 8601 format, e.g.2024-06-04T12:16:20.430056
Keep in mind that the notification_date
parameter requires the user entity to have a defined email or phone number.
patient_id
- required UUID parameter that stores patient ID. Acceptable value should be in standard UUID format.
Errors with survey creation
Wrong patient id
If the patient_id
parameter has an incorrect patient ID, your request will raise an error.
curl "https://api.infermedica.com/api/mgp/v1/surveys" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"expiration_date": "2024-06-04T12:16:20.430059",
"notification_date": "2024-06-04T12:16:20.430056",
"patient_id": "wrong_patient_id",
"sections": [
"dynamic"
],
"specialist": "neurologist",
"type": "intake",
"visit_date": "2024-06-04T12:16:20.430058",
"visit_reason": [
{
"id": "symptoms"
}
]
}'
In response, you will receive HTTP 400 Bad Request
code with the following response:
{
"detail": [
{
"type": "uuid_parsing",
"loc": [
"body",
"triage",
"patient_id"
],
"msg": "Input should be a valid UUID, invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `w` at 1",
"input": "wrong_patient_id",
"ctx": {
"error": "invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `w` at 1"
},
"url": "https://errors.pydantic.dev/2.4/v/uuid_parsing"
}
]
}
Listing surveys
To fetch a list of surveys, make a GET request to /api/mgp/v1/surveys
:
curl "https://api.infermedica.com/api/mgp/v1/surveys" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
The response will include a paginated list of surveys. The elements on a page can be limited using the limit
query parameter. Currently viewed page can be set by using the cursor
query parameter.
Example response:
{
"self": "https://api.infermedica.com/api/mgp/v1/surveys?cursor=0",
"first": "https://api.infermedica.com/api/mgp/v1/surveys?cursor=0",
"prev": null,
"next": null,
"last": "https://api.infermedica.com/api/mgp/v1/surveys?cursor=0",
"items": [
{
"notification_date": null,
"type": "intake",
"sections": [
"dynamic"
],
"visit_date": "2024-05-24T13:58:55.230198",
"visit_reason": [
{
"id": "symptoms"
}
],
"expiration_date": "2024-05-24T13:58:55.230199",
"specialist": "string",
"id": "c8a2fa04-7b2b-4afc-9460-45869b0680b2",
"status": "completed",
"patient_id": "8b767951-caf6-4f7a-b43e-a6706c64b985"
},
{
"notification_date": null,
"type": "intake",
"sections": [
"dynamic"
],
"visit_date": "2024-06-04T12:16:20.430058",
"visit_reason": [],
"expiration_date": "2024-06-04T12:16:20.430059",
"specialist": "string",
"id": "dc4a1c95-b748-4c72-9fcb-407516572f23",
"status": "new",
"patient_id": "5bb46b91-3bd0-42f4-bdae-4dcdebab262b"
}
]
}
Parameters in the response when listing surveys
Aside from all of the aforementioned above request parameters in body, there will also be an additional parameter returned that indicats a survey's status
.
status
- The survey can be in one of three statuses:new
,pending
, orcompleted
.
Request parameters in query
The following query parameters can be added in the request URL when listing surveys:
limit
- Maximum number limiting number of elements per page. Default value is10
, maximum value is50
.cursor
- Maximum number indicating currently viewed page. Default value is0
, maximum value depends on the amount of surveys created.
Retrieving a particular survey
To fetch a particular survey, make a GET request to /api/mgp/v1/surveys/{survey_id}
:
curl "https://api.infermedica.com/api/mgp/v1/surveys/ad2a837b-3378-4d54-8994-37d023a7edf8" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
In response, you will receive a 200 OK
HTTP code with the survey object in the response body.
{
"notification_date": null,
"type": "intake",
"sections": [
"dynamic"
],
"visit_date": "2024-06-04T12:16:20.430835",
"visit_reason": [
{
"id": "symptoms"
}
],
"expiration_date": "2024-06-04T12:16:20.430836",
"specialist": "string",
"id": "ad2a837b-3378-4d54-8994-37d023a7edf8",
"status": "new",
"patient_id": "5bb46b91-3bd0-42f4-bdae-4dcdebab262b"
}
Deleting a survey
To delete a survey, send a DELETE request to /api/mgp/v1/surveys/{survey_id}
. A successful response will return the status code HTTP 204
. An example DELETE request is visible below.
curl "https://api.infermedica.com/api/mgp/v1/surveys/c2b824bd-6451-4fcb-8483-b476071be849" \
-X "DELETE" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
In a successful response, you will receive 204 No Content
HTTP code. Deleted surveys will be completely removed and no longer listed in the API.
Error when deleting a survey
If you try to remove a survey that does not exist through the /surveys
endpoint by using DELETE, you will receive a 404 Not Found
HTTP response with the following message:
{
"detail": "Survey not found"
}
Updating a survey
You can update the base information in a survey by making a PATCH request to /api/mgp/v1/surveys/{survey_id}
. Please refer to the Request parameters in body section to identify the parameters possible of updating in the PATCH request.
curl "https://api.infermedica.com/api/mgp/v1/surveys/4aebc64a-e294-468c-9a40-fd234850e1c5" \
-X "PATCH" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"notification_date": "2024-06-04T12:16:20.430834",
"sections": [
"dynamic"
],
"visit_date": "2024-06-04T12:16:20.430835",
"visit_reason": [
{
"id": "symptoms"
}
],
"expiration_date": "2024-06-04T12:16:20.430836",
"specialist": "string"
}'
In response to successfully updating a survey, you will receive a 200 OK
HTTP response with the updated survey in the response body.
{
"notification_date": null,
"type": "intake",
"sections": [
"dynamic"
],
"visit_date": "2024-06-04T12:16:20.430835",
"visit_reason": [
{
"id": "symptoms"
}
],
"expiration_date": "2024-06-04T12:16:20.430836",
"specialist": "string",
"id": "ad2a837b-3378-4d54-8994-37d023a7edf8",
"status": "new",
"patient_id": "5bb46b91-3bd0-42f4-bdae-4dcdebab262b"
}
Update survey request parameters
All request parameters, aside from patient_id
, from Survey create request parameters in body can be updated through the survey update endpoint.
Keep in mind that patient_id
cannot be updated through the /surveys
endpoint by using PATCH. Instead of trying to reassign a survey to another patient, just create a new survey for the patient.
Errors on survey update
Wrong section
If any sections passed in the sections
parameter are invalid, the request will raise an error.
curl "https://api.infermedica.com/api/mgp/v1/surveys/ad2a837b-3378-4d54-8994-37d023a7edf8" \
-X "PATCH" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"expiration_date": "2024-06-04T12:16:20.430059",
"notification_date": "2024-06-04T12:16:20.430056",
"sections": [
"wrong_section"
],
"specialist": "neurologist",
"visit_date": "2024-06-04T12:16:20.430058",
"visit_reason": [
{
"id": "wrong_visit_reason"
}
]
}'
You will receive 422 Unprocessable Entity
with the following response:
{
"detail": [
{
"type": "literal_error",
"loc": [
"body",
"intake",
"sections",
0
],
"msg": "Input should be 'dynamic', 'visit_reason', 'risk_factors', 'chronic_diseases', 'specialist', 'hospitalization', 'allergies', 'message_to_doctor' or 'drugs'",
"input": "wrong_section",
"ctx": {
"expected": "'dynamic', 'visit_reason', 'risk_factors', 'chronic_diseases', 'specialist', 'hospitalization', 'allergies', 'message_to_doctor' or 'drugs'"
},
"url": "https://errors.pydantic.dev/2.4/v/literal_error"
}
]
}