Documentation
Platform API
Build your solution
Patients

Patients

A patient is an entity that represents a person's medical information within Infermedica’s system. Every patient is associated with a user.

Creating a patient

To create a patient, you must have a user already created. Each patient is assigned to a user during the creation process.

A patient can be created by adding just the user_id into the body of a POST request to the /patients endpoint https://api.infermedica.com/api/v1/patients:

cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "user_id": "729b7edf-9c47-4348-b3a8-2de4a43de0ad"
}'

In response, you will receive a patient object with all of the relevant data:

JSON
{
  "sex": null,
  "age": null,
  "evidence": null,
  "dependent": null,
  "user_id": "729b7edf-9c47-4348-b3a8-2de4a43de0ad",
  "id": "66268ace-88ea-45fa-9334-744f627ca601"
}

To create a patient that has more data, you can pass more properties in the body of the POST request to the /patients endpoint. Additional properties include age, sex, evidence, and dependent:

  • sex - attribute, accepts either the male or female value.
  • age - attribute, accepts an object with two parameters. The first parameter is unit - either year or month, The second parameter is value. Maximum and minimum values for the parameter value depend on the unit parameter. When the unit parameter is equal to year, the acceptable values for the value parameter are between 0-130. When the unit parameter is equal to month, acceptable values for the parameter value are between 1-1560.
ℹ️

Keep in mind that if the age attribute’s unit parameter is set to month and value is higher than 11, the age will be recalculated into years (ex. unit set to months and value set to 12 will be evaluated as 1 year old, and unit set to months and value set to 1560 will be evaluated to 130 years old). This does not work in reverse (ex. unit set to years and value set to 131 will not automatically recalculate unit into month. Instead, an error will be returned).

  • evidence - This is an array of “evidence” objects. To avoid errors, each evidence object in the evidence array should have three parameters:
    • The first parameter in the evidence object is id - which can be a symptom or risk factor. The id parameter accepts all of the currently available symptoms and risk factors that can be found in our Medical Knowledge endpoint https://api.infemedica.com/api/v1/knowledge/symptoms.
    • The second parameter in the evidence object is choice, which can have one of three possible values: present, absent, and unknown. The parameter choice indicates if the symptom or risk factor was confirmed by the patient as present or absent. When a patient is not sure about if a symptom or risk factor is present, the value unknown should be passed.
    • The third parameter in the evidence object is source. The source parameter can have the following possible values: initial, suggest, predefined, or red_flags. For evidence gathered during the interview, the source attribute should be entirely omitted. Learn more about evidence sources.
ℹ️

Passing evidence can indeed reduce the number of questions a patient will be asked later on in the survey. If you create a patient with e.g. at least one initial symptom, they won't be asked about providing initial symptoms in the survey. However, they will be asked about when those symptoms appeared.

  • dependent: This is a boolean attribute that accepts true or false and indicates whether the patient entity is dependent on the user. This dependency can arise if:
    • The patient is underage, typically defined as being below the age of legal adulthood (e.g., a minor child when using the Pediatrics feature).
    • The patient is an elderly person or another individual who relies on the user for care and support (e.g., the user's elderly parent).
  • user_id: This is an UUID attribute that identifies a user, used to create a patient entity
cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 20
  },
  "evidence": [
    {
      "id": "s_98",
      "choice_id": "present",
      "source": "initial"
    }
  ],
  "dependent": true,
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9"
}'

In the response for the above request, you will receive a 201 Created HTTP response with the response body seen below:

JSON
{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 20
  },
  "evidence": [
    {
      "id": "s_98",
      "choice_id": "present",
      "source": "initial"
    }
  ],
  "dependent": true,
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9",
  "id": "a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf5"
}

Errors during patient creation

During the process of creating a patient entity, various errors may occur due to incorrect or invalid data being provided in the request. These errors can arise from factors such as inadequate validation of attributes, mismatched data types, or the exceeding of acceptable limits. Below are descriptions of all of the possible errors that could arise during the patient entity creation process.

Invalid patient age

If you try to create a patient with an age value higher than acceptable, for example, 131 years, you will receive an error. Thanks to the underlying evaluation of unit as a month value, an age of 131 years could be passed as {"unit": "year", "value": 131} or as {"unit": "month", "value": 1572}. Both of the requests below will produce the same error.

cURL
curl "http://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 131
  },
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9"
}'
cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "month",
    "value": 1572
  },
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9"
}'

In response to both of the requests above, you will receive a 422 Unprocessable Entity HTTP response code with the following message:

JSON
{
  "detail": "The patient's age must be less than 131 years"
}

Trying to pass a patient age with a negative number will also result in an error. An age value below 0 will raise the same error for the unit year or month.

cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": -1
  },
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9"
}'
cURL
curl "http://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "month",
    "value": -1
  },
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9"
}'

In the response for both of the requests above, you will receive a 422 Unprocessable entity HTTP response, along with the following message:

JSON
{
  "detail": "The patient's age cannot be a negative value"
}
ℹ️

Gender and sex are a spectrum broader than just female and male. However, this technology can only currently differentiate between female and male. Due to this, always select the sex assigned to the patient at birth.

Invalid sex

Attempting to pass any value other than male or female in the sex attribute will result in an error.

cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "sex": "unknown",
  "user_id": "f22bff1e-9285-49a5-be63-afb534aaacec"
}'

In response to the above request, you will receive a 422 Unprocessable Entity HTTP response, along with the following message about an unacceptable value for the sex attribute:

JSON
{
  "detail": [
    {
      "type": "literal_error",
      "loc": [
        "body",
        "sex"
      ],
      "msg": "Input should be 'male' or 'female'",
      "input": "unknown",
      "ctx": {
        "expected": "'male' or 'female'"
      },
      "url": "https://errors.pydantic.dev/2.4/v/literal_error"
    }
  ]
}

Invalid evidence attributes

If you pass the wrong choice_id in the evidence object, e.g. 'nothing', you will receive an error indicating an incorrect value for the choice_id parameter.

cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 0
  },
  "evidence": [
    {
      "id": "s_98",
      "choice_id": "nothing",
      "source": "initial"
    }
  ],
  "user_id": "f22bff1e-9285-49a5-be63-afb534aaacec"
}'

In response to the above invalid request - caused by the unacceptable choice_id value - you will receive a 422 Unprocessable Entity HTTP response with the following message:

JSON
{
  "detail": [
    {
      "type": "literal_error",
      "loc": [
        "body",
        "evidence",
        0,
        "choice_id"
      ],
      "msg": "Input should be 'present', 'absent' or 'unknown'",
      "input": "nothing",
      "ctx": {
        "expected": "'present', 'absent' or 'unknown'"
      },
      "url": "https://errors.pydantic.dev/2.4/v/literal_error"
    }
  ]
}

When you forget to add the evidence object parameter choice_id altogether, you will receive an error indicating that the parameter is required.

cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 0
  },
  "evidence": [
    {
      "id": "s_98",
      "source": "initial"
    }
  ],
  "user_id": "f22bff1e-9285-49a5-be63-afb534aaacec"
}'

In response to the above request, you will receive a 422 Unprocessable Entity with a message indicating that the choice_id parameter is required:

JSON
{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "evidence",
        0,
        "choice_id"
      ],
      "msg": "Field required",
      "input": {
        "id": "s_98",
        "source": "initial"
      },
      "url": "https://errors.pydantic.dev/2.4/v/missing"
    }
  ]
}

Missing user ID

It is also impossible to create a patient without the required user_id attribute. Omitting the user_id attribute from POST will result in an error:

cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 0
  }
}'

In response to the above request, you will receive a 422 Unprocessable Entity HTTP response with a message indicating that the user_id attribute is missing:

JSON
{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "user_id"
      ],
      "msg": "Field required",
      "input": {
        "sex": "male",
        "age": {
          "unit": "year",
          "value": 22
        },
        "evidence": [
          {
            "id": "s_98",
            "choice_id": "present",
            "source": "initial"
          }
        ]
      },
      "url": "https://errors.pydantic.dev/2.4/v/missing"
    }
  ]
}

Invalid value in the dependent attribute

The dependent attribute is a boolean attribute that only accepts a true or false value. The request below will raise an error about a value being invalid in the dependent attribute:

cURL
curl "https://api.infermedica.com/api/v1/patients" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "dependent": "unknown",
  "user_id": "f22bff1e-9285-49a5-be63-afb534aaacec"
}'

In response to the request above, you will receive a 422 Unprocessable Entity HTTP response with an error message indicating that the value for the dependent attribute is invalid:

JSON
{
  "detail": [
    {
      "type": "bool_parsing",
      "loc": [
        "body",
        "dependent"
      ],
      "msg": "Input should be a valid boolean, unable to interpret input",
      "input": "unknown",
      "url": "https://errors.pydantic.dev/2.4/v/bool_parsing"
    }
  ]
}

Querying for patient

If you want to retrieve an already created patient, you need to make a GET request to endpoint https://api.infermedica.com/api/v1/patients/{patient_id}:

cURL
curl "https://api.infermedica.com/api/v1/patients/a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf5" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

In response, you will receive a 200 OK HTTP response with the selected patient and all of their medical data:

JSON
{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 20
  },
  "evidence": [
    {
      "id": "s_98",
      "choice_id": "present",
      "source": "initial"
    }
  ],
  "dependent": true,
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9",
  "id": "a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf5"
}

Error when querying for patient

When querying for a particular patient, you need to pass the correct patient_id UUID. The following request has an invalid UUID and is missing one character in the last part of the UUID.

cURL
curl "https://api.infermedica.com/api/v1/patients/a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

In response, you will receive a 422 Unprocessable Entity HTTP response, along with a message indicating which part of the UUID is incorrect:

JSON
{
    "detail": [
        {
            "type": "uuid_parsing",
            "loc": [
                "path",
                "patient_id"
            ],
            "msg": "Input should be a valid UUID, invalid group length in group 4: expected 12, found 11",
            "input": "a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf",
            "ctx": {
                "error": "invalid group length in group 4: expected 12, found 11"
            },
            "url": "https://errors.pydantic.dev/2.4/v/uuid_parsing"
        }
    ]
}

Querying for multiple patients

All of the patients created can be accessed through the GET endpoint https://api.infermedica.com/api/v1/patients. This endpoint accepts additional query parameters like cursor (currently viewed page) and limit (the number of patients per viewed page). The query parameter limit accepts values between 1-50:

cURL
curl "http://api.infermedica.com/api/v1/patients?cursor=0&limit=10" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

In response, you can receive up to 50 patients - if you have that many created already - from the GET endpoint above. In our example, we could receive up to ten patients (as determined by the limit) but only receive two as only two patients have been created so far:

JSON
{
  "self": "http://api.infermedica.com/api/v1/patients?limit=10&cursor=0",
  "first": "http://api.infermedica.com/api/v1/patients?limit=10&cursor=0",
  "prev": null,
  "next": null,
  "last": "http://api.infermedica.com/api/v1/patients?limit=10&cursor=0",
  "items": [
    {
      "sex": "male",
      "age": {
        "unit": "year",
        "value": 20
      },
      "evidence": [
        {
          "id": "s_98",
          "choice_id": "present",
          "source": "initial"
        }
      ],
      "dependent": true,
      "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9",
      "id": "b4d8112b-8f7c-4864-97fb-c628f1c59ac2"
    },
    {
      "sex": "female",
      "age": {
        "unit": "year",
        "value": 76
      },
      "evidence": [
        {
          "id": "s_21",
          "choice_id": "present",
          "source": "initial"
        }
      ],
      "dependent": false,
      "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9",
      "id": "a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf5"
    }
  ]
}

Updating a patient’s information

To update the medical data of an already created patient, make a PATCH request to the /patients endpoint. Make sure to have their specific patient_id and use url https://api.infermedica.com/api/v1/:

ℹ️

Keep in mind that the user_id attribute cannot be updated when updating a patient entity.

cURL
curl "https://api.infermedica.com/api/v1/patients/a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf5" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "female",
  "age": {
    "unit": "year",
    "value": 76
  },
  "evidence": [
    {
      "id": "s_21",
      "choice_id": "present",
      "source": "initial"
    }
  ],
  "dependent": false
}'

In response, you will receive a 200 OK HTTP response, along with the updated patient object:

JSON
{
  "sex": "female",
  "age": {
    "unit": "year",
    "value": 76
  },
  "evidence": [
    {
      "id": "s_21",
      "choice_id": "present",
      "source": "initial"
    }
  ],
  "dependent": false,
  "user_id": "c599e21b-3795-4f02-a14e-b46884f8a0c9",
  "id": "a9d16b2a-dfa0-41ad-9c27-87f7c2dd9cf5"
}

Errors when updating a patient

Below are descriptions of errors that you might encounter when updating a patient entity if you try to pass the incorrect values for attributes.

Invalid patient age

If you attempt to update a patient entity with an age value higher than acceptable ex. 131 years, you will receive an error. Due to the underlying evaluation of unit as a month value, an age of 131 years could be passed either as {"unit": "year", "value": 131} or as {"unit": "month", "value": 1572}:

cURL
curl "https://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 131
  }
}'
cURL
curl "https://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "month",
    "value": 1572
  }
}'

In response to both of the requests above, you will receive a 422 Unprocessable Entity HTTP response code with the following message:

JSON
{
  "detail": "The patient's age must be less than 131 years"
}

Attempting to pass a negative age value for a patient will also result in an error. An age value below 0 will raise the same error for both the year and month unit.

cURL
curl "https://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": -1
  }
}'
cURL
curl "http://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "month",
    "value": -1
  }
}'

In response to both of the requests below, you will receive a 422 Unprocessable entity status code with the following message:

JSON
{
  "detail": "The patient's age cannot be a negative value"
}
ℹ️

Gender and sex are a spectrum broader than just female and male. However, this technology can only currently differentiate between female and male. Always select the sex assigned to the patient at birth.

Invalid sex

Attempting to pass any value other than male or female in the sex attribute will also result in an error.

cURL
curl "https://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "unknown"
}'

In response to the above request, you will receive a 422 Unprocessable Entity HTTP response with a message indicating that there is an unacceptable value for the sex attribute:

JSON
{
  "detail": [
    {
      "type": "literal_error",
      "loc": [
        "body",
        "sex"
      ],
      "msg": "Input should be 'male' or 'female'",
      "input": "unknown",
      "ctx": {
        "expected": "'male' or 'female'"
      },
      "url": "https://errors.pydantic.dev/2.4/v/literal_error"
    }
  ]
}

Invalid evidence attributes

If you pass the wrong choice_id in the evidence object - for example, 'nothing' - you will receive an error indicating that there is an incorrect value for the choice_id parameter.

cURL
curl "https://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 0
  },
  "evidence": [
    {
      "id": "s_98",
      "choice_id": "nothing",
      "source": "initial"
    }
  ]
}'

In response to the above invalid request - due to an unacceptable choice_id value - you will receive a 422 Unprocessable Entity HTTP response with the following message:

JSON
{
  "detail": [
    {
      "type": "literal_error",
      "loc": [
        "body",
        "evidence",
        0,
        "choice_id"
      ],
      "msg": "Input should be 'present', 'absent' or 'unknown'",
      "input": "nothing",
      "ctx": {
        "expected": "'present', 'absent' or 'unknown'"
      },
      "url": "https://errors.pydantic.dev/2.4/v/literal_error"
    }
  ]
}

When you forget to add the choice_id parameter to the evidence object altogether, you will receive an error indicating that the parameter is required.

cURL
curl "https://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "sex": "male",
  "age": {
    "unit": "year",
    "value": 0
  },
  "evidence": [
    {
      "id": "s_98",
      "source": "initial"
    }
  ]
}'

In response to the above request, you will receive a 422 Unprocessable Entity HTTP response with a message indicating that the choice_id field is required:

JSON
{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "evidence",
        0,
        "choice_id"
      ],
      "msg": "Field required",
      "input": {
        "id": "s_98",
        "source": "initial"
      },
      "url": "https://errors.pydantic.dev/2.4/v/missing"
    }
  ]
}

Invalid value in the dependent attribute

The dependent attribute is a boolean attribute that accepts either a true or false value. The request below will raise an error about an invalid value being found in the dependent attribute:

cURL
curl "https://api.infermedica.com/api/v1/patients/f2663f52-2b8b-43d9-bf2d-b78a68da51fe" \
  -X "PATCH" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "dependent": "unknown"
}'

In response to the above request, you will receive a 422 Unprocessable Entity HTTP response with an error message indicating that the value for the dependent attribute is invalid:

JSON
{
  "detail": [
    {
      "type": "bool_parsing",
      "loc": [
        "body",
        "dependent"
      ],
      "msg": "Input should be a valid boolean, unable to interpret input",
      "input": "unknown",
      "url": "https://errors.pydantic.dev/2.4/v/bool_parsing"
    }
  ]
}

Deleting a patient

To remove a particular patient, use the /patients endpoint and make a DELETE request, passing their patient_id via the url http://api.infermedica.com/api/v1/patients/{patient_id}:

cURL
curl "https://api.infermedica.com/api/v1/patients/b7983af3-24b5-41dd-a621-ae4bb03e319c" \
  -X "DELETE" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

If a request is successful, once the patient is deleted you will receive the HTTP code 204 No Content

Error when deleting a patient

If you try to remove a patient that does not exist by making a DELETE request, you will receive a 404 Not Found HTTP response with the following message:

JSON
{
  "detail": "Patient not found"
}
UsersSurveys