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 "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:
{
"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 themale
orfemale
value.age
- attribute, accepts an object with two parameters. The first parameter isunit
- eitheryear
ormonth
, The second parameter isvalue
. Maximum and minimum values for the parametervalue
depend on theunit
parameter. When theunit
parameter is equal toyear
, the acceptable values for thevalue
parameter are between0
-130
. When theunit
parameter is equal tomonth
, acceptable values for the parametervalue
are between1
-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 theevidence
array should have three parameters:- The first parameter in the
evidence
object isid
- which can be a symptom or risk factor. Theid
parameter accepts all of the currently available symptoms and risk factors that can be found in our Medical Knowledge endpointhttps://api.infemedica.com/api/v1/knowledge/symptoms
. - The second parameter in the
evidence
object ischoice
, which can have one of three possible values:present
,absent
, andunknown
. The parameterchoice
indicates if the symptom or risk factor was confirmed by the patient aspresent
orabsent
. When a patient is not sure about if a symptom or risk factor is present, the valueunknown
should be passed. - The third parameter in the
evidence
object issource
. Thesource
parameter can have the following possible values:initial
,suggest
,predefined
, orred_flags
. For evidence gathered during the interview, thesource
attribute should be entirely omitted. Learn more about evidence sources.
- The first parameter in the
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 acceptstrue
orfalse
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 "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:
{
"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 "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 "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:
{
"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 "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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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 "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:
{
"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 "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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"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 "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:
{
"detail": "Patient not found"
}