Users list

Request description

Endpoint: /users/list/:limit/:lastUserId
Method: GET

The following parameters can be passed through the URL:

• limit: specifies the maximum number of users to return in the query. Positive integer
  
• lastUserId: specifies the identifier of the last userId returned. This parameter is used if pagination is to be performed. Requires limit
  

Both parameters are optional. Without limit, all the users of the organization are returned.

Header

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <accessToken>"
}

Note: the <accessToken> is obtained as a result of the authentication. The authentication flow you have to follow depends on the access mode, see Access modes.

Access modes

This endpoint accepts two kinds of access token. The users you get back, and their structure, depend on which one you use:

Platform user

Returns a page of users. Use limit to set the page size and lastUserId to continue from the last user you received. When a page returns fewer users than limit, there are no more pages.

Response structure

type ListUsersResponseType = {
  users: IUser[]; //  List of users related to the query
};

Below we will describe the structure of the IUser interface:

interface IUser = {
   id: string, // Unique user identifier
   fullName: string, // User fullname
   email: string, // User email
   userType: UserType, // User role in the organization
   lastLogin?: string, // Timestamp (ms) of the user's last login, sent as a numeric string, e.g. "1790861416924". Not present if the user has never logged in
   createdAt: number, // Timestamp (ms) of the user creation time, sent as a number
   groupId: string // Group ID related to the user. "NOT-DEFINED" when the user has no group
}

type UserType = 'ORGANIZATION_OWNER' | 'ORGANIZATION_ADMIN' | 'REGULAR'

Dictation user

Returns every user of the corporate dictation server of the organization associated with your credentials.

Pagination is not available

Response structure

type ListDictationUsersResponseType = {
  users: DictationUser[]; // Complete list of dictation server users
};

Below we will describe the structure of the DictationUser interface:

interface DictationUser = {
   login: string, // Unique login, used to update or delete the user
   name: string, // User full name
   email: string, // User email
   organization: string, // Free-text organization label
   specialtyCode: string, // Speciality code
   rolType: number, // License type assigned by the platform
   active: boolean // Whether the user can sign in
}

login is the value you have to send in the URL of Edit user and Delete user.

See Invite user for details about specialtyCode. rolType is read only: it is assigned by the platform and cannot be set through this API.

Responses

Correct response

{
  "users": [
    {
      "id": "mock-user-id",
      "fullName": "mock-full-name",
      "email": "mock@mock.com",
      "userType": "REGULAR",
      "lastLogin": "1700000000000",
      "createdAt": 1690000000000,
      "groupId": "mock-group-id"
    }
  ]
}

{
  "users": [
    {
      "login": "jperez",
      "name": "Juan Perez",
      "email": "jperez@hospital.com",
      "organization": "Hospital X",
      "specialtyCode": "1",
      "rolType": 2,
      "active": true
    }
  ]
}

Wrong responses

{
  "message": "Unauthorized"
}

Description: this error occurs when endpoint authorizers fail to validate the token sent in the request header.

type ListUsersResponseType = {
  errorType: LIST_USERS_ERROR_TYPE;
  errorMessage: string;
  message?: string;
  details?: object[];
};

enum LIST_USERS_ERROR_TYPE {
  INVALID_LIMIT_VALUE = "invalidLimitValue", // limit is not a positive integer
  INVALID_USER_ID = "invaliduSERId",         // lastUserId is not a valid user identifier (the value is spelled exactly like this)
}

{
  "errorMessage": "Invalid limit",
  "message": "Invalid limit",
  "errorType": "invalidLimitValue",
  "details": [
    /* validation detail */
  ]
}

{
  "message": "Forbidden"
}

{
  "message": "Dictation server rejected the operation"
}

{
  "message": "Tenant not found"
}

Description: there is no dictation server for your organization in this environment.

{
  "message": "Dictation server unavailable"
}

Description: the dictation server could not return the list.

{
  "message": "Dictation server did not respond in time"
}

Description: the dictation server did not answer within the allowed time.