Users
A user represents an individual who interacts directly with the Platform API. Users are considered foundational entities, without which it’s impossible to create a patient. Every patient within the system is associated with a user, whether that patient also be the person doing the interview or a dependent of the person doing the interview.
The user entity stores information of a mostly non-medical nature while the patient entity stores information of a mostly medical nature. While both entities could refer to the same person, the information within the two entities will never overlap. The user entity will always refer to the person interacting with Infermedica while the patient entity could refer to that person or one of their dependents.
Creating a User
To create a user, you don't need to provide any attributes in the body of the POST request:
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{}'
Attributes email
and phone
might be necessary for an Intake workflow. Please refer to our intake
documentation to learn more.
In response, you will receive a user ID in the id
field and empty email
and phone
attributes:
{
"id": "152ec3b3-e6a8-4938-8500-154be3decb3e",
"email": null,
"phone": null
}
However, you can create a user with an email
, phone
, or both properties if you choose:
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"email": "user@example.net",
"phone": "+498999998999"
}'
In response to creating a user with the email
and phone
attributes filled in, you will receive a user ID with id
filled in, along with the email
and phone
attributes also already filled in:
{
"id": "729b7edf-9c47-4348-b3a8-2de4a43de0ad",
"email": "user@example.net",
"phone": "+498999998999"
}
Errors during user creation
During user creation, you might encounter several errors related to the validation of the email
or phone
attributes. These errors are described below.
Errors due to incorrect email value
If you try to pass an incorrect email
value after the '@' sign, you will receive an error indicating that an invalid email
attribute has been used:
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"email": "user@example",
"phone": "+498999998999"
}'
In response, you will receive a HTTP response - 422 Unprocessable Entity
- due to an incorrect email
value after @
:
{
"detail": [
{
"type": "value_error",
"loc": [
"body",
"email"
],
"msg": "value is not a valid email address: The part after the @-sign is not valid. It should have a period.",
"input": "user@example",
"ctx": {
"reason": "The part after the @-sign is not valid. It should have a period."
}
}
]
}
If the email
value is incorrect before the @
sign, you will also receive an error indicating that an invalid email
attribute value has been used:
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"email": "@example.net",
"phone": "+498999998999"
}'
In response to a request with an incorrect email
value before the @
sign, you will receive a HTTP response -422 Unprocessable Entity
- with the following message:
{
"detail": [
{
"type": "value_error",
"loc": [
"body",
"email"
],
"msg": "value is not a valid email address: There must be something before the @-sign.",
"input": "@example.net",
"ctx": {
"reason": "There must be something before the @-sign."
}
}
]
}
Keep in mind that at the moment SMS functionality doesn’t work for US clients.
Errors due to incorrect phone value
If you try to pass an incorrect value in the phone
attribute, errors could arise for various reasons. These include:
- The phone number you're trying to pass is too short.
- You're trying to use an international dialing code that is currently not acceptable.
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"email": "user@example.net",
"phone": "+49899999"
}'
In response to the above request, you will receive a 422 Unprocessable Entity
response with the following message:
{
"detail": [
{
"type": "value_error",
"loc": [
"body",
"phone"
],
"msg": "Value error, value is not a valid phone number",
"input": "+49899999",
"ctx": {
"error": {}
},
"url": "https://errors.pydantic.dev/2.4/v/value_error"
}
]
}
Errors due to an already existing email or phone
If you try to create a user with an email
or phone
that is already assigned to another user, you will receive an error:
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"email": "user@example.net"
}'
curl "https://api.infermedica.com/api/mgp/v1/users" \
-X "POST" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"phone": "+498999998999"
}'
In response to both of the above requests - which try to create a user entity with an email
or phone
value that is already taken by another user - a 409 Conflict
HTTP response will be received with the following message:
{
"detail": "Email and SMS must be unique"
}
Retrieving a user with user ID
To retrieve an already created user, you need to provide a user_id
via the GET endpoint https://api.infermedica.com/api/mgp/v1/users/{user_id}
, which is used for retrieving specific users:
curl "https://api.infermedica.com/api/mgp/v1/users/729b7edf-9c47-4348-b3a8-2de4a43de0ad" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
In response, you will receive:
{
"id": "729b7edf-9c47-4348-b3a8-2de4a43de0ad",
"email": "user@example.net",
"phone": "+498999998999"
}
Error when retrieving a user with user ID
When trying to retrieve a particular user, you need to pass the correct form of the user_id
UUID. If you make a request with one character missing in the last part of the UUID, like the one presented below, your request will result in an error.
A UUID (Universally Unique Identifier) is a 128-bit number used to uniquely identify information in computer systems, commonly represented as a 36-character string of 32 hexadecimal digits and four hyphens. It ensures uniqueness across different entities, systems, and networks.
curl "https://api.infermedica.com/api/mgp/v1/users/729b7edf-9c47-4348-b3a8-2de4a43de0a" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
As a result of passing a user_id
UUID with one character missing in the last part of the UUID, you will receive a 422 Unprocessable Entity
HTTP response with the following message:
{
"detail": [
{
"type": "uuid_parsing",
"loc": [
"path",
"user_id"
],
"msg": "Input should be a valid UUID, invalid group length in group 4: expected 12, found 11",
"input": "729b7edf-9c47-4348-b3a8-2de4a43de0a",
"ctx": {
"error": "invalid group length in group 4: expected 12, found 11"
},
"url": "https://errors.pydantic.dev/2.4/v/uuid_parsing"
}
]
}
Retrieving a list of users
To retrieve a list of users, send a GET request to the /users
endpoint, specifying the cursor
query parameter for the page number you want to view and the limit
query parameter for the number of users displayed per page.
curl "https://api.infermedica.com/api/mgp/v1/users?cursor=0&limit=10" \
-X "GET" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
In response, you will get a list of users like this one:
{
"self": "https://api.infermedica.com/api/mgp/v1/users?limit=10&cursor=0",
"first": "https://api.infermedica.com/api/mgp/v1/users?limit=10&cursor=0",
"prev": null,
"next": null,
"last": "https://api.infermedica.com/api/mgp/v1/users?limit=10&cursor=0",
"items": [
{
"id": "3059a36a-9804-436f-847b-c637323edb63",
"email": "user@example.net",
"phone": "+498999998999"
},
{
"id": "729b7edf-9c47-4348-b3a8-2de4a43de0ad",
"email": "user@example.net",
"phone": "+498999998999"
}
]
}
Updating a user with user ID
To update a user’s phone number or email address, make a PATCH request to the /users
endpoint at https://api.infermedica.com/api/mgp/v1/users/{user_id}
. Make sure you replace user_id
with the specific ID of the user you're updating.
curl "https://api.infermedica.com/api/mgp/v1/users/c599e21b-3795-4f02-a14e-b46884f8a0c9" \
-X "PATCH" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"id": "c599e21b-3795-4f02-a14e-b46884f8a0c9",
"email": "user1@example.net",
"phone": "+498999998999"
}'
In response, you will receive the user ID along with the updated data:
{
"id": "c599e21b-3795-4f02-a14e-b46884f8a0c9",
"email": "user1@example.net",
"phone": "+498999998000"
}
Deleting a user with user ID
When there is no longer a need to store a user’s information, you can make a DELETE request to the /users
endpoint to delete it. Make sure to have the correct user_id
, then make a DELETE request to https://api.infermedica.com/api/mgp/v1/{user_id}
:
curl "https://api.infermedica.com/api/mgp/v1/users/c599e21b-3795-4f02-a14e-b46884f8a0c9" \
-X "DELETE" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
When a user is successfully deleted, you will receive a response with HTTP status code 204 No Content
Error when deleting a user
If you try to remove a user that no longer exists - for example, because you have already recently deleted the user - using a request like the one below, you will receive an error in the response.
curl "https://api.infermedica.com/api/mgp/v1/users/c599e21b-3795-4f02-a14e-b46884f8a0c9" \
-X "DELETE" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
In response to the request above, should the user entity no longer exist, you will receive 404 Not Found
HTTP response.