Invite user

Request description

Endpoint: /users/invite-to-organization
Method: POST

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, and the request body depends on which one you use:

The endpoint, method and headers are identical in both cases. The payload and the possible errors are not.

Platform user

Payload

{
  "fullName": "mock-full-name",
  "email": "mock@mock.com",
  "groupId": "group-id",
  "userType": "REGULAR"
}

Payload structure

type InviteUserPayloadType = {
  fullName: string;   // User full name
  email: string;      // User email. An invitation is sent to this address
  groupId?: string;   // Group of the user. Must be the id of a group of your organization
  userType: UserType; // User role in the organization
};

type UserType = "ORGANIZATION_OWNER" | "ORGANIZATION_ADMIN" | "REGULAR";

Field rules

If the email already has an account on the platform (for example, in another organization), no new user is created: the existing user is added to your organization and the response includes their id.

Dictation user

Creates a user in the corporate dictation server of the organization associated with your credentials. You do not send the organization: it is resolved from your access token.

Payload

{
  "login": "jperez",
  "password": "mock-password",
  "fullName": "Juan Perez",
  "email": "jperez@hospital.com",
  "specialtyCode": "1",
  "organization": "Hospital X"
}

Payload structure

type InviteDictationUserPayloadType = {
  login: string; // Unique login in the dictation server
  password: string; // Initial password
  fullName: string; // User full name
  email: string; // User email
  specialtyCode: string; // Speciality code (see below)
  organization?: string; // Free-text organization label
};

Field rules

The license type of the created user is assigned automatically and cannot be set through this API. Any additional field sent in the payload is ignored.

About specialtyCode

An unknown speciality code is rejected by the dictation server and returns 502.

Responses

Correct response

{
  // empty response
}

{
  "message": "User added to organization successfully",
  "id": "mock-user-id"
}

type InviteUserSuccessResponseType = {
  message?: string; // Only when an existing user was added to your organization
  id?: string;      // Only when an existing user was added to your organization
};

{
  "message": "User created successfully",
  "login": "jperez"
}

Wrong responses

{
  "message": "Unauthorized"
}

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

{
  "errorType": "invalidRequestFormat",
  "errorMessage": "Fullname is required",
  "message": "Fullname is required",
  "details": [
    /* validation detail */
  ]
}

type InviteUserResponseType = {
  errorType: INVITE_USER_ERROR_TYPE;
  errorMessage: string;
  message?: string;    // Present on validation errors
  details?: object[];  // Present on validation errors
};

enum INVITE_USER_ERROR_TYPE {
  INVALID_REQUEST_FORMAT = "invalidRequestFormat",
  EMAIL_ALREADY_EXISTS_IN_ORGANIZATION = "emailAlreadyExistsInOrganization",
}

{
  "errorType": "emailDoesNotExist",
  "errorMessage": "Email does not exist"
}

{
  "errorType": "notAllowedResource",
  "errorMessage": "Unauthorized",
  "message": "Unauthorized"
}

{
  "errorType": "invalidRequestFormat",
  "errorMessage": "Login is required",
  "message": "Login is required",
  "details": [
    /* validation detail */
  ]
}

Description: errorMessage identifies the first field that failed. Possible values:

{
  "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": "There is already a user with the same login"
}

Description: that login is already in use. Logins are unique and are not reused.

{
  "message": "Dictation server unavailable"
}

Description: the dictation server could not complete the request. Also returned when the speciality code is not valid.

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

Description: the dictation server did not answer within the allowed time. The user may or may not have been created; check before retrying.