Documentation
Platform API
Build your solution
Users

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

JSON
{
  "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
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:

JSON
{
    "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
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 @ :

JSON
{
  "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
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:

JSON
{
  "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
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:

JSON
{
  "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
curl "https://api.infermedica.com/api/mgp/v1/users" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
  "email": "user@example.net"
}'
cURL
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:

JSON
{
  "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
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:

JSON
{
    "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
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:

JSON
{
    "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
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:

JSON
{
  "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
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:

JSON
{
  "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
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
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.

IntakePatients