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

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.

JSON

{
  "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 is intake
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, and drugs.
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 the id attribute identifying the reason for a visit, e.g. [{"id": "symptoms"}]. Possible values for the id 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

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:

JSON

{
  "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

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:

JSON

{
  "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, or completed.

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 is 10, maximum value is 50.
cursor - Maximum number indicating currently viewed page. Default value is 0, 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

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.

JSON

{
  "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

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:

JSON

{
  "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

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.

JSON

{
  "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

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:

JSON

{
  "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"
    }
  ]
}

Patients Navigating Question Flows