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

Prefilling survey with symptoms and risk factors

The prefilling feature allows you to start a survey with known symptoms or risk factors already provided. This feature adds flexibility in how initial medical evidence is handled at the begining of an interview.

Why use evidence prefilling?

Prefilling medical evidence is particularly useful in two scenarios:

1. Skip initial symptom selection (by default)
When symptoms are definitively known (e.g., user clicked "I have a headache" in your app), you can skip the screen with initial symptoms, moving directly to detailed questions about those symptoms.

2. Allow user confirmation (when enabled)
When the evidence might be uncertain or needs verification (e.g., auto-detected symptoms from previous visits, symptoms inferred from search queries, or risk factors imported from external health records), enable prefilling to show the symptoms question with pre-selected values. This allows patients to:

• confirm whether the pre-selected symptoms are still accurate;
• remove symptoms that no longer apply;
• add new symptoms they're experiencing;
• ensure the assessment is based on verified, current information.

How prefilling of evidence works

When you include evidence in the survey creation request with source: "initial":

• By default: The initial symptoms question is skipped, and the interview continues with symptoms defined outside interview;
• When enabled: The symptoms question appears with the provided symptoms pre-selected, allowing users to review and modify them. The prefilled values are returned in the question's user_answer field, making it easy to track which symptoms were confirmed or modified by the user.

Example: Creating a survey with prefilled symptoms

To prefill initial symptoms, include them in the evidence array when creating a survey:

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": "triage",
  "evidence": [
    {
      "id": "s_21",
      "choice_id": "present",
      "source": "initial"
    },
    {
      "id": "s_98",
      "choice_id": "present",
      "source": "initial"
    }
  ]
}'

In this example, the survey starts with headache (s_21) and fever (s_98) already reported as present symptoms.

Prefilling risk factors

You can also prefill risk factors using the same approach. Risk factor IDs start with p_:

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": "triage",
  "evidence": [
    {
      "id": "p_28",
      "choice_id": "present",
      "source": "initial"
    },
    {
      "id": "p_146",
      "choice_id": "present",
      "source": "initial"
    }
  ]
}'

Prefilled symptoms question response example

When prefilling is enabled, fetching the symptoms question returns the pre-filled symptoms in the user_answer field:

curl "https://api.infermedica.com/api/mgp/v1/surveys/{survey_id}/questions/current" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response with prefilled symptoms:

{
  "id": "symptoms",
  "index": 3,
  "question": {
    "text": "What symptoms are you experiencing?"
  },
  "answer_type": "symptoms",
  "user_answer": {
    "answer": [
      {
        "id": "s_21",
        "name": "Headache",
        "choice_id": "present"
      },
      {
        "id": "s_98",
        "name": "Fever",
        "choice_id": "present"
      }
    ]
  }
}

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"
      ],
      "expiration_date": "2024-05-24T13:58:55.230199",
      "id": "c8a2fa04-7b2b-4afc-9460-45869b0680b2",
      "status": "completed",
      "patient_id": "8b767951-caf6-4f7a-b43e-a6706c64b985"
    },
    {
      "notification_date": null,
      "type": "intake",
      "sections": [
        "dynamic"
      ],
      "expiration_date": "2024-06-04T12:16:20.430059",
      "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 indicates 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