Surveys

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.

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:

Errors with survey creation

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, 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}:

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.

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.

Errors on survey update