API Docs

Rest User

Overview

There are two basic types of user accounts in Alma: Internal users and External users.
Internal users are users that exist only in Alma. They are created manually by library staff and are managed entirely within the library's scope.
External users are users that are stored and managed outside the library's scope, usually in another system maintained by the institution (for example, in a Student Information System).
These users' information is loaded into Alma and is synchronized on a regular basis.
See User Types for more details.

This XSD describes the user object that is used in SIS load (version 2), and in the Users API.
SIS load takes only external information into account: Internal users are not updated at all, and Internal segments that are related to an external user are not updated at all.
User API behavior is different: It does update internal user's information and updates internal segments that are related to an external user as well.

Data Dictionary

Click here to download rest_user.xsd

user

Description: User Object.

Field	Type	Description
record_type	with attr.	The type of user record. Possible codes are listed in 'AddNewUserOptions' code table: Contact, Staff, Public. Mandatory In User API. On SIS load, this field is determined according to the SIS profile. The valid values for this parameter are controlled by the code-table: AddNewUserOptions. These are the currently defined values for your institution: Code Description
primary_id	string255Length	The primary identifier of the user. Mandatory In User API. For new users in SIS load , if not supplied, the system will generate a default based on the first and the last name. Note that the primary_id is case insensitive.
first_name	string255Length	The user's first name.
middle_name	string255Length	The user's middle name.
last_name	string255Length	The user's last name.
full_name	string600Length	The user's full name. Output parameter.
pin_number	string255Length	A four-digit number which serves as a password for the user to log on to the selfcheck machine (SIP2). On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details.
user_title	with attr.	The user's title Possible codes are listed in the 'UserTitles' code table. On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details.
job_category	with attr.	The types of jobs the user performs in the library, such as Cataloger, Circulation Desk Operator, and so forth. Possible values are listed in 'Job Titles' code table. On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details. The valid values for this parameter are controlled by the code-table: JobTitles. These are the currently defined values for your institution: Code Description
job_description	string255Length	General description of the user's job.
gender	with attr.	The user's gender. Possible codes are listed in the 'Genders' code table. The valid values for this parameter are controlled by the code-table: Genders. These are the currently defined values for your institution: Code Description
user_group	with attr.	The group within the institution to which the user belongs. Possible codes are listed in 'User Groups' code table. Rules for user group usage are define in 'UserRecordTypeUserGroup' mapping table. On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details. The valid values for this parameter are controlled by the code-table: UserGroups. These are the currently defined values for your institution: Code Description
campus_code	with attr.	The code of the campus related to the user. Possible codes are listed in the "Campus List" of the general configuration menu. On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details.
web_site_url	string255Length	The web site address related to the user.
cataloger_level	with attr.	The cataloger level of the user. The cataloger level serves to control which catalogers can edit and update records which have been edited and updated by other users.
preferred_language	with attr.	The user's preferred language. Possible codes are listed in 'User Preferred Language' code table. Default: en. On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details. The valid values for this parameter are controlled by the code-table: UserPreferredLanguage. These are the currently defined values for your institution: Code Description
birth_date	date	The user's birth date.
expiry_date	date	The estimated date when the user is expected to leave the institution.
purge_date	date	The date on which the user is purged from the system.
account_type	with attr.	The user's account type. Possible code are listed in 'User Types - User' code table. This field is mandatory in the User API. In the PUT action, it is possible to update Internal user to be External. It is NOT possible to update External user to be Internal. On SIS load, users are always created as "External". The valid values for this parameter are controlled by the code-table: UserUserType. These are the currently defined values for your institution: Code Description
external_id	string255Length	The external system from which the user was loaded into Alma. Relevant only for External users. This field is mandatory during the POST and PUT actions for external users, and must match a valid SIS external system profile. On SIS load, it is filled with the SIS profile code.
password	string255Length	user's password. Relevant for internal users only. Due to security issues, it is returned empty in the GET action. Note that in the PUT action password can be updated, but if left empty - the existing password will be kept.
force_password_change	string4Length	Set this field to 'TRUE' to prompt user to change the password on next log in. Relevant for internal users only.
status	with attr.	Status of user account. Possible codes are listed in 'Content Structure Status' code table. Default is Active. The valid values for this parameter are controlled by the code-table: ContentStructureStatus. These are the currently defined values for your institution: Code Description
status_date	date	The date of the last update to user status.
last_patron_activity_date	date	The last date that specific activities were executed. The relevant activities can be found in OLH
requests	int with attr.	Number of requests for user. Output parameter.
loans	int with attr.	Number of loans for user. Output parameter.
fees	float with attr.	Fines/fees active balance for user Output parameter.
contact_info	contact_info	List of the user's contacts information.
user_identifiers	user_identifiers	List of the user's additional identifiers.
user_roles	user_roles	List of the user's roles. SIS: roles are NOT part of the SIS load. POST action: If list of roles is supplied, these will be the roles. If list of roles was not supplied in the POST action, the user will be created with roles according to the role assignment rules (General > User Management Configuration > Configuration Menu > Roles and Registration > Role Assignment Rules). PUT action: If list of roles is supplied, it will replace the existing roles. If list of roles was not supplied in the PUT action, the existing roles will be kept (note that the roles behavior is different than the other segments: all user segments are deleted if the incoming list is empty. Only roles are kept in such case).
user_blocks	user_blocks	List of the user's blocks.
user_notes	user_notes	List of the user's related notes.
user_statistics	user_statistics	List of the user's related statistics.
proxy_for_users	proxy_for_users	A list of the user's proxy users
rs_libraries	rs_libraries	List of the user's related resource sharing libraries. On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details.
library_notices	library_notices	List of the user's library notices. On SIS synch this field will not be replaced if it was updated manually. For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name. See blog for more details.
source_link_id	string	Reference to the system internal unique identifier at the institution identified by source_institution_code . This field is populated at the copy user record (linked account). The value is equal to the linking_id at the source institution (identified by source_institution_code).
source_institution_code	string	The code of the institution where the source user record is managed. This field is populated at the copy user record (linked account).
linking_id	string	The system internal unique identifier of the source user account. This field is populated at the source user record. This can be used to fetch copies of the user record (linked accounts in other institutions) by calling the Get-User API with the source_institution_code parameter.
pref_first_name	string255Length	The user's preferred first name.
pref_middle_name	string255Length	The user's preferred middle name.
pref_last_name	string255Length	The user's preferred last name.
pref_name_suffix	string255Length	The user's name suffix. This field is only relevant to Esploro researchers.
is_researcher	boolean	Indication whether the user is a researcher. Default is false. For Esploro use only.
researcher	researcher	researcher information. For Esploro use only.

 

user_roles

Description: List of the user's roles.
SIS: roles are NOT part of the SIS load.
POST action: If list of roles is supplied- these will be the roles.
If list of roles was not supplied in the POST action, the user will be created with roles according to the role assignment rules
(General > User Management Configuration > Configuration Menu > Roles and Registration > Role Assignment Rules).
PUT action: If list of roles is supplied- it will replace the existing roles.
If list of roles was not supplied in the PUT action, the existing roles will be kept (note that the roles behavior is different than the other segments: all user segments are deleted if the incoming list is empty. Only roles are kept in such case).

Field	Type	Description
user_role	user_role	Specific user's role.

 

user_role

Description: Specific user's role.

Field	Type	Description
status	with attr.	The user's role status. Possible codes are listed in 'User Roles Status Codes' code table. If empty, default value is Active, if an illegal value is given, default is Inactive. The valid values for this parameter are controlled by the code-table: UserRoleStatus. These are the currently defined values for your institution: Code Description
scope	with attr.	The campus/library to which the role applies.
role_type	with attr.	The user's role. Possible codes are listed in 'User Roles' code table. The valid values for this parameter are controlled by the code-table: HFrUserRoles.roleType. These are the currently defined values for your institution: Code Description
expiry_date	date	The date after which the user no longer has the role.
parameters	parameters	Role's related parameters.

 

user_statistics

Description: List of user's statistics.
SIS: In case of new user, these segments will be marked as "external".
In case of synchronization, this list will replace the existing external statistics. Internal statistics will be kept.
POST action: The segments will be created as external or as internal according to the "segment_type" attribute.
PUT action: Incoming internal segments (based on the "segment_type" attribute) will replace the existing internal segments.
Incoming external segments (based on the "segment_type" attribute) will replace the existing external segments.
If the incoming list is empty, existing segments will be deleted.

Field	Type	Description
user_statistic	user_statistic	Specific user statistic.

 

user_statistic

Description: Specific user statistic.

Field	Type	Description
statistic_category	with attr.	The statistic's Categories. Possible codes are listed in 'User Statistical Categories' code table. The valid values for this parameter are controlled by the code-table: UserStatCategories. These are the currently defined values for your institution: Code Description
category_type	with attr.	The statistic's type. Possible codes are listed in 'User Category Types' code table. Output parameter. The valid values for this parameter are controlled by the code-table: UserStatisticalTypes. These are the currently defined values for your institution: Code Description
statistic_owner	string	Library owner of the statistics (library code). Relevant only for libraries who limit fulfilment data by library scope.
statistic_note	string2000Length	The statistic's related note.

 

proxy_for_users

Description: A list of proxy information for users.

Field	Type	Description
proxy_for_user	proxy_for_user	A specific user's proxy or substitute.

 

proxy_for_user

Description: A particular proxy for a user.

Field	Type	Description
primary_id	string255Length	The primary identifier.
full_name	string600Length	The user's first and last name.
proxy_type	string255Length	This is relevant only for Esploro. Type should be RESEARCH.

 

user_notes

Description: List of the user's related notes.
SIS: In case of new user, these segments will be marked as "external".
In case of synchronization, this list will replace the existing external notes. Internal notes will be kept.
POST action: The segments will be created as external or as internal according to the "segment_type" attribute.
PUT action: Incoming internal segments (based on the "segment_type" attribute) will replace the existing internal segments.
Incoming external segments (based on the "segment_type" attribute) will replace the existing external segments.
If the incoming list is empty, existing segments will be deleted.

Field	Type	Description
user_note	user_note	Specific user's note.

 

user_note

Description: Specific user's note.

Field	Type	Description
note_type	with attr.	The note's type. Possible codes are listed in the 'Note Types' code table. Mandatory. The valid values for this parameter are controlled by the code-table: NoteTypes. These are the currently defined values for your institution: Code Description
note_text	string2000Length	The note's text. Mandatory.
user_viewable	boolean	Indication whether the user is able to view the note. Default is false.
popup_note	boolean	Indication whether the note supposed to popup while entering patron services. Default is false.
created_by	string255Length	Creator of the note.
created_date	dateTime	Creation date of the note.
note_owner	string	Library owner of the note (library code). Relevant only for libraries who limit fulfilment data by library scope.

 

user_blocks

Description: List of user's blocks.
SIS: In case of new user, these segments will be marked as "external".
In case of synchronization, this list will replace the existing external blocks. Internal blocks will be kept.
POST action: The segments will be created as external or as internal according to the "segment_type" attribute.
PUT action: Incoming internal segments (based on the "segment_type" attribute) will replace the existing internal segments.
Incoming external segments (based on the "segment_type" attribute) will replace the existing external segments.
If the incoming list is empty, existing segments will be deleted.

Field	Type	Description
user_block	user_block	A specific user's block.

 

user_block

Description: A specific user's block.

Field	Type	Description
block_type	with attr.	The block type. Possible codes are listed in the 'User Block Types' code table. Default is 'GENERAL'. The valid values for this parameter are controlled by the code-table: UserBlockTypes. These are the currently defined values for your institution: Code Description
block_description	with attr.	The block's description. Mandatory. Possible codes are listed in the 'User Block Description' code table. The valid values for this parameter are controlled by the code-table: UserBlockDescription. These are the currently defined values for your institution: Code Description
block_status	string255Length	The block's status. Possible values: Active, Inactive. Default is Active.
block_note	string2000Length	The block's related note.
created_by	string255Length	Creator of the block
created_date	dateTime	Creation date of the block
expiry_date	dateTime	Expiration date of the block
item_loan_id	string	Internal identifier of the loan which generated this block.
block_owner	string	Library owner of the block (library code). Relevant only for libraries who limit fulfilment data by library scope.

 

contact_info

Description: List of the user's contacts information.
SIS: In case of new user, these segments will be marked as "external".
In case of synchronization, this list will replace the existing external contacts. Internal contacts will be kept.
POST action: The segments will be created as external or as internal according to the "segment_type" attribute.
PUT action: Incoming internal segments (based on the "segment_type" attribute) will replace the existing internal segments.
Incoming external segments (based on the "segment_type" attribute) will replace the existing external segments.
If the incoming list is empty, existing segments will be deleted.

Field	Type	Description
addresses	addresses	List of user's addresses.
emails	emails	List of user's email addresses.
phones	phones	List of user's phone numbers.

 

emails

Description: List of user's email addresses.

Field	Type	Description
email	email	Specific user's email address.

 

email

Description: Specific user's email address.

Field	Type	Description
email_address	string255Length	The email address. Mandatory.
description	string255Length	The email address' related description.
email_types	email_types

 

email_types

Description: The different email types.
Mandatory.

Field	Type	Description
email_type	with attr.	Possible codes are listed in the 'UserEmailTypes' code table. The valid values for this parameter are controlled by the code-table: MT_UserRecordType2EmailType_by_CT_UserEmailTypes_source1:staff,public,contact_source2:anything. These are the currently defined values for your institution: Code Description

 

phones

Description: List of user's phone numbers.

Field	Type	Description
phone	phone	Specific user's phone number.

 

phone

Description: Specific user's phone number.

Field	Type	Description
phone_number	string255Length	The phone number. Mandatory.
phone_types	phone_types	The different Phone types. Mandatory.

 

phone_types

Description: Phone types.

Field	Type	Description
phone_type	with attr.	Possible values are listed in the 'UserPhoneTypes' code table. The valid values for this parameter are controlled by the code-table: MT_UserRecordType2PhoneType_by_CT_UserPhoneTypes_source1:staff,public,contact_source2:anything. These are the currently defined values for your institution: Code Description

 

addresses

Description: List of user's addresses.

Field	Type	Description
address	address	Specific user's address.

 

address

Description: Specific user's address.

Field	Type	Description
line1	string	Line 1 of the address. Mandatory.
line2	string255Length	Line 2 of the address.
line3	string255Length	Line 3 of the address.
line4	string255Length	Line 4 of the address.
line5	string255Length	Line 5 of the address.
city	string255Length	The address' relevant city. Mandatory.
state_province	string255Length	The address' relevant state.
postal_code	string255Length	The address' relevant postal code.
country	with attr.	The address' relevant country. Possible codes are listed in the 'Country Codes' code table. The valid values for this parameter are controlled by the code-table: CountryCodes. These are the currently defined values for your institution: Code Description
address_note	string1000Length	The address' related note.
start_date	date	The date from which the address is deemed to be active.
end_date	date	The date after which the address is no longer active.
address_types	address_types	Address types. Mandatory.

 

address_types

Description: Address types.

Field	Type	Description
address_type	with attr.	Possible values are listed in the 'UserAddressTypes' code table. The valid values for this parameter are controlled by the code-table: MT_UserRecordType2AddressType_by_CT_UserAddressTypes_source1:staff,public,contact_source2:anything. These are the currently defined values for your institution: Code Description

 

user_identifiers

Description: List of the user's additional identifiers.
For more information regarding case sensitivity see here.
SIS: In case of new user, these segments will be marked as "external".
In case of synchronization, this list will replace the existing external identifiers. Internal identifiers will be kept.
POST action: The segments will be created as external or as internal according to the "segment_type" attribute.
PUT action: Incoming internal segments (based on the "segment_type" attribute) will replace the existing internal segments.
Incoming external segments (based on the "segment_type" attribute) will replace the existing external segments.
If the incoming list is empty, existing segments will be deleted.

Field	Type	Description
user_identifier	user_identifier	Specific user's identifier.

 

rs_libraries

Description: List of the user's related resource sharing libraries.
On SIS synch this field will not be replaced if it was updated manually.
For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name.

Field	Type	Description
rs_library	rs_library	Specific user's related resource sharing library.

 

rs_library

Description: Specific user's related resource sharing library.

Field	Type	Description
code	with attr.	The code of the resource sharing library. Possible codes are libraries which are defined as "Resource Sharing".

 

library_notices

Description: List of the user's library notices.
On SIS synch this field will not be replaced if it was updated manually.
For external users in PUT action: this field will not be replaced if it was updated manually, unless 'override' parameter is sent with the field's name.

Field	Type	Description
library_notice	library_notice	Specific user's library notice.

 

library_notice

Description: Specific user's library notice.

Field	Type	Description
code	with attr.	The code of the library notice. Possible codes are listed in 'Library Notices Opt In Display' code table. The valid values for this parameter are controlled by the code-table: LibraryNoticesOptInDisplay. These are the currently defined values for your institution: Code Description
value	boolean

 

user_identifier

Description: Specific user's identifier.

Field	Type	Description
id_type	with attr.	The identifier type. Possible codes are listed in 'User Identifier Type' code table. Mandatory. The valid values for this parameter are controlled by the code-table: UserIdentifierTypes. These are the currently defined values for your institution: Code Description
value	string255Length	The identifier value. Mandatory. For more information regarding case sensitivity see here.
note	string2000Length	identifier's note.
status	string255Length	identifier's status.

 

parameters

Description: Role's related parameters.

Field	Type	Description
parameter	parameter	Role's specific parameter.

 

parameter

Description: Role's specific parameter.

Field	Type	Description
type	with attr.	The parameter's type. Possible values: CirculationDesk, MetadataType, ServiceUnit, CantEditRestrictedUsers.
scope	with attr.	The library to which the parameter applies. Used for role of type ServiceUnit.
value	with attr.	Parameter's related value: CirculationDesk - A valid Circulation desk code. ServiceUnit - A valid work order department code CantEditRestrictedUsers - true or false.

 

string4Length

string4Length is a xs:string with xs:restriction - see XSD for details.

string10Length

string10Length is a xs:string with xs:restriction - see XSD for details.

string20Length

string20Length is a xs:string with xs:restriction - see XSD for details.

string50Length

string50Length is a xs:string with xs:restriction - see XSD for details.

string255Length

string255Length is a xs:string with xs:restriction - see XSD for details.

string600Length

string600Length is a xs:string with xs:restriction - see XSD for details.

string1000Length

string1000Length is a xs:string with xs:restriction - see XSD for details.

string2000Length

string2000Length is a xs:string with xs:restriction - see XSD for details.

string4000Length

string4000Length is a xs:string with xs:restriction - see XSD for details.

Samples

XML

JSON

__