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.

FieldTypeDescription
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:
CodeDescription
primary_idstring255LengthThe 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_namestring255LengthThe user's first name.
middle_namestring255LengthThe user's middle name.
last_namestring255LengthThe user's last name.
full_namestring600LengthThe user's full name. Output parameter.
pin_numberstring255LengthA 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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), 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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), 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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), 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:
CodeDescription
job_descriptionstring255LengthGeneral 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:
CodeDescription
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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), 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:
CodeDescription
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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), unless 'override' parameter is sent with the field's name.
See blog for more details.
web_site_urlstring255LengthThe 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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), 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:
CodeDescription
birth_datedateThe user's birth date.
expiry_datedateThe estimated date when the user is expected to leave the institution.
purge_datedateThe 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:
CodeDescription
external_idstring255LengthThe 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.
passwordstring255Lengthuser'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_changestring4Length
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:
CodeDescription
status_datedateThe date of the last update to user status.
requestsint with attr. Number of requests for user.
Output parameter.
loansint with attr. Number of loans for user.
Output parameter.
feesfloat with attr. Fines/fees active balance for user
Output parameter.
contact_infocontact_infoList of the user's contacts information.
user_identifiersuser_identifiersList of the user's additional identifiers.
user_rolesuser_rolesList 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).
Note: For the "Digital Inventory Operator" role at least one metadata-type should be added as a role-parameter.
user_blocksuser_blocksList of the user's blocks.
user_notesuser_notesList of the user's related notes.
user_statisticsuser_statisticsList of the user's related statistics.
proxy_for_usersproxy_for_users A list of the user's proxy users
rs_librariesrs_librariesList of the user's related resource sharing libraries.
On SIS synch this field will not be replaced if it was updated manually (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), unless 'override' parameter is sent with the field's name.
See blog for more details.
library_noticeslibrary_noticesList of the user's library notices.
On SIS synch this field will not be replaced if it was updated manually (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), unless 'override' parameter is sent with the field's name.
See blog for more details.
source_link_idstringReference 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_codestringThe code of the institution where the source user record is managed.
This field is populated at the copy user record (linked account).
linking_idstring 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_namestring255LengthThe user's preferred first name.
pref_middle_namestring255LengthThe user's preferred middle name.
pref_last_namestring255LengthThe user's preferred last name.
pref_name_suffixstring255LengthThe user's name suffix. This field is only relevant to Esploro researchers.
is_researcherbooleanIndication whether the user is a researcher.
Default is false. For Esploro use only.
researcherresearcherresearcher 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).
Note: For the "Digital Inventory Operator" role at least one metadata-type should be added as a role-parameter.

FieldTypeDescription
user_roleuser_roleSpecific user's role.

 

user_role

Description: Specific user's role.

FieldTypeDescription
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:
CodeDescription
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:
CodeDescription
expiry_datedateThe date after which the user no longer has the role.
parametersparametersRole'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.

FieldTypeDescription
user_statisticuser_statisticSpecific user statistic.

 

user_statistic

Description: Specific user statistic.

FieldTypeDescription
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:
CodeDescription
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:
CodeDescription
statistic_notestring2000LengthThe statistic's related note.

 

proxy_for_users

Description: A list of proxy information for users.

FieldTypeDescription
proxy_for_userproxy_for_user A specific user's proxy or substitute.

 

proxy_for_user

Description: A particular proxy for a user.

FieldTypeDescription
primary_idstring255LengthThe primary identifier.
full_namestring600LengthThe user's first and last name.

 

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.

FieldTypeDescription
user_noteuser_noteSpecific user's note.

 

user_note

Description: Specific user's note.

FieldTypeDescription
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:
CodeDescription
note_textstring2000LengthThe note's text.
Mandatory.
user_viewablebooleanIndication whether the user is able to view the note.
Default is false.
popup_notebooleanIndication whether the note supposed to popup while entering patron services.
Default is false.
created_bystring255LengthCreator of the note.
created_datedateTimeCreation date of the note.

 

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.

FieldTypeDescription
user_blockuser_blockA specific user's block.

 

user_block

Description: A specific user's block.

FieldTypeDescription
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:
CodeDescription
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:
CodeDescription
block_statusstring255LengthThe block's status.
Possible values: Active, Inactive.
Default is Active.
block_notestring2000LengthThe block's related note.
created_bystring255LengthCreator of the block
created_datedateTimeCreation date of the block
expiry_datedateTimeExpiration date of the block
item_loan_idstringInternal identifier of the loan which generated this block.

 

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.

FieldTypeDescription
addressesaddressesList of user's addresses.
emailsemailsList of user's email addresses.
phonesphonesList of user's phone numbers.

 

emails

Description: List of user's email addresses.

FieldTypeDescription
emailemailSpecific user's email address.

 

email

Description: Specific user's email address.

FieldTypeDescription
email_addressstring255LengthThe email address. Mandatory.
descriptionstring255LengthThe email address' related description.
email_typesemail_types

 

email_types

Description: The different email types.
Mandatory.

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

 

phones

Description: List of user's phone numbers.

FieldTypeDescription
phonephoneSpecific user's phone number.

 

phone

Description: Specific user's phone number.

FieldTypeDescription
phone_numberstring255LengthThe phone number.
Mandatory.
phone_typesphone_typesThe different Phone types.
Mandatory.

 

phone_types

Description: Phone types.

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

 

addresses

Description: List of user's addresses.

FieldTypeDescription
addressaddressSpecific user's address.

 

address

Description: Specific user's address.

FieldTypeDescription
line1stringLine 1 of the address.
Mandatory.
line2string255LengthLine 2 of the address.
line3string255LengthLine 3 of the address.
line4string255LengthLine 4 of the address.
line5string255LengthLine 5 of the address.
citystring255LengthThe address' relevant city.
Mandatory.
state_provincestring255LengthThe address' relevant state.
postal_codestring255LengthThe 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:
CodeDescription
address_notestring1000LengthThe address' related note.
start_datedateThe date from which the address is deemed to be active.
end_datedateThe date after which the address is no longer active.
address_typesaddress_typesAddress types.
Mandatory.

 

address_types

Description: Address types.

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

 

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.

FieldTypeDescription
user_identifieruser_identifierSpecific 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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), unless 'override' parameter is sent with the field's name.

FieldTypeDescription
rs_libraryrs_librarySpecific user's related resource sharing library.

 

rs_library

Description: Specific user's related resource sharing library.

FieldTypeDescription
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 (or if empty in the incoming user record).
For external users in PUT action: this field will not be replaced if it was updated manually (or if empty in the incoming user record), unless 'override' parameter is sent with the field's name.

FieldTypeDescription
library_noticelibrary_noticeSpecific user's library notice.

 

library_notice

Description: Specific user's library notice.

FieldTypeDescription
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:
CodeDescription
valueboolean

 

user_identifier

Description: Specific user's identifier.

FieldTypeDescription
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:
CodeDescription
valuestring255LengthThe identifier value.
Mandatory.
For more information regarding case sensitivity see here.
notestring2000Lengthidentifier's note.
statusstring255Lengthidentifier's status.

 

parameters

Description: Role's related parameters.

FieldTypeDescription
parameterparameterRole's specific parameter.

 

parameter

Description: Role's specific parameter.

FieldTypeDescription
type with attr. The parameter's type.
Possible values: CirculationDesk, MetadataType, ServiceUnit.
value with attr. Parameter's related value.
The valid values for this parameter are controlled by the code-table: JobTitles. These are the currently defined values for your institution:
CodeDescription

 

string4Length
string4Lengthis a xs:string with xs:restriction - see XSD for details.
string10Length
string10Lengthis a xs:string with xs:restriction - see XSD for details.
string20Length
string20Lengthis a xs:string with xs:restriction - see XSD for details.
string50Length
string50Lengthis a xs:string with xs:restriction - see XSD for details.
string255Length
string255Lengthis a xs:string with xs:restriction - see XSD for details.
string600Length
string600Lengthis a xs:string with xs:restriction - see XSD for details.
string1000Length
string1000Lengthis a xs:string with xs:restriction - see XSD for details.
string2000Length
string2000Lengthis a xs:string with xs:restriction - see XSD for details.
string4000Length
string4000Lengthis a xs:string with xs:restriction - see XSD for details.

Samples

XML
JSON
__