SenSeeAct Documentation

# User controller (/user)

This controller contains endpoints related to user profiles, roles and status. The profile includes the user’s language and timezone. There is also an endpoint to completely delete a user.

Endpoints in alphabetical order:

/user/ (GET)
/user/ (PUT)
/user/ (DELETE)
/user/active (PUT)
/user/list (GET)
/user/groups (GET)
/user/role (PUT)

# /list (GET)

/user/list GET
Description
Returns all users with short info about each user. The users are sorted by email address.
Authorization
Only admins can call this endpoint.
URL parameters
–
Content
–
Response (application/json)
JSON with user objects. A user object has the following properties:
userid
User ID. It identifies a user in SenSeeAct and is normally a UUID. For users that were created in an old version of SenSeeAct, it may still be an email address.
email
Email address. This is always in lower case. It is unique so it can be used to identify a user, but any user data in the rest of the database uses the user ID.
role
PATIENT, PROFESSIONAL, ADMIN
active
true if the user is active, false if the user is inactive. An inactive user cannot log in or call any endpoints that require authentication.
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/user/list
X-Auth-Token: ...
Response 
[
    {
        "userid": "b43f784d76c44e7a9ae0370b91521753",  
        "email": "user@example.com",
        "role": "PATIENT",
        "active": true
    },
    ...
]

# / (GET)

/user/ GET
Description
Returns the profile of the specified user by user ID or email address.
Authorization
All users can access their own profile.
Patients can only access their own profile.
Professionals can access the users to whom they were granted access.
Admins can access all users.
URL parameters
user
(optional) User ID of the user whose profile should be returned. You can specify either ‘user’ or ‘email’. If both are empty or not specified, you will get your own profile.
email
(optional) Email address of the user whose profile should be returned.
Content
–
Response (application/json)
JSON object. The following properties are always set:
userid
User ID. This is always set. It identifies a user in SenSeeAct and is normally a UUID. For users that were created in an old version of SenSeeAct, it may still be an email address.
email
Email address. This is always set and it is always in lower case. It is unique so it can be used to identify a user, but any user data in the rest of the database uses the user ID.
emailVerified
true if the email address has been verified. When a user creates a new account or changes their email address, an email with a confirmation link is sent. When the user confirms it, this property becomes true.
emailPending- Verification
If the user changed their email address with

PUT /user/

 and their current email address has been verified, then the new email address will be put here. An email with a confirmation link has been sent to the new address. When the user confirms it, the email address from this property will be moved to email.
hasTemporaryEmail
true if the user has a temporary email address. This is the case if the user signed up with

/auth/signup-temporary-user

. It becomes false when the user changes the email address with

PUT /user/

.
hasTemporary- Password
true if the user has a temporary password. This is the case if the user signed up with

/auth/signup-temporary-user

. It becomes false when the user changes their password with

/auth/change-password

.
role
PATIENT, PROFESSIONAL, ADMIN. This is always set.
active
true if the user is active, false if the user is inactive. An inactive user cannot log in or call any endpoints that require authentication.
created
The time when the user was created, formatted as 2023-09-20T10:15:00.000+02:00. The timezone may also be specified as Z for UTC.
lastActive
The time when the user was last active, formatted as 2023-09-20T10:15:00.000+02:00. The timezone may also be specified as Z for UTC.
The following properties are optional:
gender
MALE, FEMALE, OTHER
maritalStatus
SINGLE, PARTNER, MARRIED, DIVORCED, WIDOW
title
Title
initials
Initials of the first names formatted as A.B.C.
firstName
First name. This should be the familiar first name used to address the person in friendly language.
officialFirstNames
Official first names
prefixes
Prefixes for the last name. Languages such as Dutch have prefixes for last names that should be ignored when sorting.
lastName
Last name. This should be the familiar last name used to address the person in friendly language.
officialLastNames
Official last names
fullName
Full name. This can be used for apps that do not distinguish between first name and last name.
nickName
Nickname.
altEmail
Alternative email address
birthDate
Birth date formatted like 1965-09-23
deceasedDate
If the user has deceased, this is the date of decease, formatted like 2020-09-23.
idNumber
Identification number. This could be the personal identification number for government services or in a hospital administration system.
landlinePhone
Landline phone number. It could include characters such as hyphens, parentheses and spaces. The format is not validated.
mobilePhone
Mobile phone number. It could include characters such as hyphens, parentheses and spaces. The format is not validated.
street
Street name
streetNumber
House number in the street. This can be any string.
addressExtra
Extra address lines
postalCode
Postal code. The format is not validated.
town
Town name
departmentCode
String code for the department
extraInfo
Any extra information
localeCode
Locale code. This can be used for the user’s preferred language. For example: en or en_GB. It can be an ISO 639-1 language code, and optionally an ISO 3166-1 alpha-2 country code, separated by an underscore.
languageFormality
The formality that the user prefers to be addressed with. This can be FORMAL or INFORMAL.
timeZone
Time zone. This should be a location-based time zone ID from the tz database. For example: Europe/Amsterdam.
status
Status. This property can be used if your application needs more status information than property active.
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/user/
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Response 
{
    "userid": "b43f784d76c44e7a9ae0370b91521753",  
    "email": "user@example.com",
    "emailVerified": true,
    "emailPendingVerification": null,
    "hasTemporaryEmail": false,
    "hasTemporaryPassword": false,
    "role": "PATIENT",
    "active": true,
    "created": "2023-09-20T10:15:00.000+02:00",
    "lastActive": "2023-09-20T10:15:00.000+02:00",
    "gender": "FEMALE",
    "maritalStatus": null,
    "title": null,
    "initials": null,
    "firstName": null,
    "officialFirstNames": null,
    "prefixes": null,
    "lastName": null,
    "officialLastNames": null,
    "fullName": null,
    "nickName": null,
    "altEmail": null,
    "birthDate": "1963-09-23",
    "deceasedDate": null,
    "idNumber": null,
    "landlinePhone": null,
    "mobilePhone": null,
    "street": null,
    "streetNumber": null,
    "addressExtra": null,
    "postalCode": null,
    "town": null,
    "departmentCode": null,
    "extraInfo": null,
    "localeCode": "en_GB",
    "languageFormality": "INFORMAL",
    "timeZone": "Europe/Amsterdam",
    "status": null
}

# / (PUT)

/user/ PUT
Description
Updates the profile of the specified user.
Authorization
All users can access their own profile.
Patients can only access their own profile.
Professionals can access the users to whom they were granted access.
Admins can access all users.
URL parameters
user
(optional) User ID of the user whose profile should be updated. If empty or not specified, you will update your own profile.
emailTemplate
(optional) The name of a custom email template that is used when you change the email address and an email with a confirmation link is sent. The templates are defined in class EmailTemplateRepository.
Content
JSON object with the following properties. Any property may be omitted. In that case its value in the user profile will remain unchanged.

The following properties cannot be changed with this endpoint. If you specify them, they are ignored.

  • userid
  • emailVerified
  • emailPendingVerification
  • hasTemporaryEmail
  • hasTemporaryPassword
  • role
  • active
  • created
  • lastActive

There is special handling of property email. If you specify it, it must not be empty and it must be a unique email address. When you change the email address, an email will be sent to both the old and new email address, and the latter contains a confirmation link. If you change the email address while the current address has been verified, then the new address will be put in emailPendingVerification, until the user opened the confirmation link. Only then will the new address be activated and moved to email.

Apart from the properties mentioned above, any other property can be changed and may be set to null. Note the difference between omitting a property, which leaves the value in the user profile unchanged, and setting the property to null, which sets the value in the profile to null.

userid
User ID. You cannot change this property. If you set it, it must be the same as the current value.
email
Email address. This is always stored in lower case. It is unique so it can be used to identify a user. Any user data in the rest of the database uses the user ID, so you can change the email address here. If you change it, it must remain unique.
If you change the email address while the current address has been verified, then the new address will be put in emailPendingVerification. See more info above.
emailVerified
true if the email address has been verified. You cannot change this property with this endpoint. When a user creates a new account or changes their email address, an email with a confirmation link is sent. When the user confirms it, this property becomes true.
emailPending- Verification
You cannot change this property directly. If you change email and the current email address has been verified, then the new email address will be put here. See more info above.
hasTemporaryEmail
You cannot change this property directly. It is true if the user has a temporary email address. This is the case if the user signed up with

/auth/signup-temporary-user

. It becomes false when you change the email address with this endpoint.
hasTemporary- Password
You cannot change this property with this endpoint. It is true if the user has a temporary password. This is the case if the user signed up with

/auth/signup-temporary-user

. It becomes false when the user changes their password with

/auth/change-password

.
role
PATIENT, PROFESSIONAL, ADMIN. You cannot change this property with this endpoint. If you set it, it must be the same as the current value. The role can be changed with

/user/role

.
active
true if the user is active, false if the user is inactive. An inactive user cannot log in or call any endpoints that require authentication. You cannot change this property with this endpoint. If you set it, it must be the same as the current value. You can activate or deactivate a user with

/user/active

.
created
The time when the user was created, formatted as 2023-09-20T10:15:00.000+02:00. The timezone may also be specified as Z for UTC. You cannot change this property.
lastActive
The time when the user was last active, formatted as 2023-09-20T10:15:00.000+02:00. The timezone may also be specified as Z for UTC. You cannot change this property.
gender
MALE, FEMALE, OTHER
maritalStatus
SINGLE, PARTNER, MARRIED, DIVORCED, WIDOW
title
Title
initials
Initials of the first names formatted as A.B.C.
firstName
First name. This should be the familiar first name used to address the person in friendly language.
officialFirstNames
Official first names
prefixes
Prefixes for the last name. Languages such as Dutch have prefixes for last names that should be ignored when sorting.
lastName
Last name. This should be the familiar last name used to address the person in friendly language.
officialLastNames
Official last names
fullName
Full name. This can be used for apps that do not distinguish between first name and last name.
nickName
Nickname.
altEmail
Alternative email address
birthDate
Birth date formatted like 1965-09-23
deceasedDate
If the user has deceased, this is the date of decease, formatted like 2020-09-23.
idNumber
Identification number. This could be the personal identification number for government services or in a hospital administration system.
landlinePhone
Landline phone number. It could include characters such as hyphens, parentheses and spaces. The format is not validated.
mobilePhone
Mobile phone number. It could include characters such as hyphens, parentheses and spaces. The format is not validated.
street
Street name
streetNumber
House number in the street. This can be any string.
addressExtra
Extra address lines
postalCode
Postal code. The format is not validated.
town
Town name
departmentCode
String code for the department
extraInfo
Any extra information
localeCode
Locale code. This can be used for the user’s preferred language. For example: en or en_GB. It can be an ISO 639-1 language code, and optionally an ISO 3166-1 alpha-2 country code, separated by an underscore.
languageFormality
The formality that the user prefers to be addressed with. This can be FORMAL or INFORMAL.
timeZone
Time zone. This should be a location-based time zone ID from the tz database. For example: Europe/Amsterdam.
status
Status. This property can be used if your application needs more status information than property active.
Response (application/json)
JSON object in the same format as the input or the result of

GET /user/

.
Example
Request 
PUT https://www.example.com/servlets/senseeact/v6.1.0/user/
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: …
Content-Type: application/json
 
{
    "userid": "b43f784d76c44e7a9ae0370b91521753",
    "email": "user@example.com",
    "emailVerified": true,
    "emailPendingVerification": null,
    "hasTemporaryEmail": false,
    "hasTemporaryPassword": false,
    "role": "PATIENT",
    "active": true,
    "created": "2023-09-20T10:15:00.000+02:00",
    "lastActive": "2023-09-20T10:15:00.000+02:00",
    "gender": "FEMALE",
    "maritalStatus": null,
    "title": null,
    "initials": null,
    "firstName": null,
    "officialFirstNames": null,
    "prefixes": null,
    "lastName": null,
    "officialLastNames": null,
    "fullName": null,
    "nickName": null,
    "altEmail": null,
    "birthDate": "1963-09-23",
    "deceasedDate": null,
    "idNumber": null,
    "landlinePhone": null,
    "mobilePhone": null,
    "street": null,
    "streetNumber": null,
    "addressExtra": null,
    "postalCode": null,
    "town": null,
    "departmentCode": null,
    "extraInfo": null,
    "localeCode": "en_GB",
    "languageFormality": "INFORMAL",
    "timeZone": "Europe/Amsterdam",
    "status": null
}
Response 
{
    "userid": "b43f784d76c44e7a9ae0370b91521753",
    "email": "user@example.com",
    ...
}

# / (DELETE)

/user/ DELETE
Description
Completely deletes a user and all related data from all projects. If you run this endpoint as an admin and the specified user does not exist, then it does nothing.
Authorization
All users can delete themselves.
Patients and professionals can only delete themselves.
Admins can delete any user.
URL parameters
user
User ID of the user to delete.
Content
–
Response
–
Example
Request 
DELETE https://www.example.com/servlets/senseeact/v6.1.0/user/
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Response 
–

# /role

/user/role PUT
Description
Sets the role of another user.
Authorization
Only admins can call this endpoint. You can only set the role of another user.
URL parameters
user
User ID of the user whose role should be set
role
PATIENT, PROFESSIONAL, ADMIN
Content
–
Response
–
Example
Request 
POST https://www.example.com/servlets/senseeact/v6.1.0/user/role
    ?user=b43f784d76c44e7a9ae0370b91521753
    &role=PROFESSIONAL
X-Auth-Token: ...
Response 
–

# /active

/user/active PUT
Description
Activates or deactivates a user. An inactive user cannot log in or call any endpoints that require authentication.
Authorization
Only admins can call this endpoint. You can only activate or deactivate another user.
URL parameters
user
User ID of the user whose role should be set
active
true if the user should be active, false if the user should be inactive
Content
–
Response
–
Example
Request 
POST https://www.example.com/servlets/senseeact/v6.1.0/user/active
    ?user=b43f784d76c44e7a9ae0370b91521753
    &active=true
X-Auth-Token: ...
Response 
–

# /groups

/user/groups GET
Description
Returns the names of the groups where the specified user is a member.
Authorization
All users can get the groups for themselves.
Admins can get the groups for any user.
URL parameters
user
(optional) User ID of the user whose groups should be returned. If empty or not specified, you will get the groups for yourself.
Content
–
Response (application/json)
JSON array with the group names.
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/user/groups
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Response 
[
    "group@example.com",
    ...
]

← /group →