API Documentation | Hosted CSV Roster

OVERVIEW

This document outlines the CSV format required for automated resident data importing done via sftp or curl. Electing this option means that your institution will deploy an SFTP server which the Roompact system will connect to and download a .csv file. This will be configured as a nightly cronjob that runs automatically.

SFTP CSV Transfer Process

CSV FORMAT

In order to use this import option, the a CSV file with following format must be adhered to. The following columns may be included in the CSV file. Column names must be identical to the ones listed below. Any columns that are present in the CSV file but not listed below will be ignored. More detailed information about each field can be found in the following section.

user_email
user_uid
user_first
user_preferred_first
user_last
user_phone
user_pronouns
user_student_id
user_address
user_birthdate
user_age
user_image_data
user_image_url
user_start_date
user_end_date
override_user_deactivate
building_name
floor_name
suite_name
room_name

DATA FIELDS

The resident import interface accepts the following fields for each user. Basic fields such as user_first, user_last, and user_email are required during initial user creation and should be included in most subsequent requests. The user_uid field is also required if the school using Single Sign-On (CAS or Shibboleth). Fields that are not included with a request will be neither modified nor deleted. All field labels are case sensitive, and must be supplied exactly as indicated in the FIELD column below.

Requirement Levels

As defined in RFC 2119.

REQUIRED - This field MUST be included with every request.
RECOMMENDED - This field SHOULD be included every request under normal conditions. Read the field description to understand the full implications of omitting this field.
OPTIONAL - This field is independent of all other fields and is only required when the data needs to be changed.

FIELD	REQUIREMENT LEVEL	DESCRIPTION
`user_email`	REQUIRED	The email address of the user. Acts as a unique identifier for users at institutions that do not provide a unique user identifier (`user_uid` field). This field is used as part of the user’s login credentials unless the institution is using a Single Sign-On integration with Roompact. This field MUST be included for each user with all requests.
`user_uid`	RECOMMENDED	An explicit unique identifier for a user. This field MUST contain the user’s Single Sign-On identifier if the institution has established CAS or Shibboleth login integration with Roompact. If a user’s email is subject to change at any point, this field is REQUIRED in order to track the user. Once set, this field MUST NOT be changed and will always be treated as a reference to the same user.
`user_first`	RECOMMENDED	The user’s first name. Any middle names should be included with this field (e.g. if the user’s name is “George Walker Bush” the `user_first` field should be “George Walker”). This field is REQUIRED during initial user creation.
`user_preferred_first`	OPTIONAL	The user’s preferred first name. If set, this field will be used instead of the `user_first` field for the user’s first name, and the `user_first` field will be ignored. If technical limitations do not allow a separate field to be used for preferred names, the `user_first` field can instead be populated with the preferred name of the user.
`user_last`	RECOMMENDED	The user’s last name. This field MUST be included during initial user creation.
`user_phone`	RECOMMENDED	The user’s phone number. All non-numerical characters will be stripped from the input data before saving (e.g. “(234) 567-8900” will be saved as “2345678900”). Providing this field is recommended because text messages are used as a primary method of communication between staff and residents in many features in Roompact. Not providing this field will result in email getting used as a fallback communication method.
`user_pronouns`	OPTIONAL	The user’s pronouns. This field is not case sensitive and it will be displayed on the user’s profile page as provided.
`user_student_id`	OPTIONAL	The user’s student ID number. This field will be used exclusively in the client side component of the Roompact software, and not as a unique identifier in the system. No format is expected and it will be displayed on the user’s profile page as provided.
`user_address`	OPTIONAL	The user’s campus address. Will be displayed on their profile page or accessible in some other form through the client side component of the Roompact software.
`user_birthdate`	OPTIONAL	The date of birth of the user. The date should be sent as a string adhering to the following YYYY-MM-DD format (Example: 1995-06-25)
`user_age`	OPTIONAL	The age of the user. The age should be sent as a string (Example: 19). If an user_age value is provided, the user_birthdate will be hidden on staff and resident views.
`user_image_data`	OPTIONAL	This field should contain a base64 encoded BLOB of user image data. Note: that the maximum size of a POST request accepted by the Roompact webservers is 100MB. When updating large numbers of users, if the total size of all of the images exceeds this limit, the update should be split into multiple smaller requests.
`user_image_url`	OPTIONAL	This field should contain a url to the user’s image. Note that if the `user_image_url` field is included in a request, the `user_image_data` field will be ignored if both are included. Sending requests with both fields should be avoided. Images that are not served over SSL will automatically be downloaded and rehosted by Roompact.
`user_start_date`	RECOMMENDED	The start date of the user’s room assignment as indicated by the `building_name`, `floor_name`, `suite_name`, and `room_name` fields (described below). The date should be sent as a string in YYYY-MM-DD format (Example: 2020-04-20). This field is REQUIRED if the `user_end_date` field is provided, otherwise both fields will be ignored. The date supplied in this field must precede the date in the `user_end_date` field. If a user has a different room assignment in the system with an overlapping date range, that assignment will be shortened to accommodate the new assignment. If a user has a room assignment in the system for the same room that has ended within 30 days of the supplied start date, the existing room assignment will be extended.
`user_end_date`	RECOMMENDED	The end date of the user’s room assignment as indicated by the `building_name`, `floor_name`, `suite_name`, and `room_name` fields. This field is REQUIRED if the `user_start_date` field is provided, otherwise both fields will be ignored. See the description for `user_start_date` for data format and behavior details.
`override_user_deactivate`	OPTIONAL	This field can be used explicitly deactivate a user, ending the user’s current assignment as well as deleting all existing future assignments. For deactivation to happen field should be set to the string “TRUE”. When this deactivation occurs, all other field updates for this user to be ignored.
`building_name`	RECOMMENDED	This field should contain the string name of the building/hall that the user should be placed in for a room assignment. This field is REQUIRED during room assignment creation or change, even if the user is not being moved between buildings. Examples: “Lincoln Hall”, “Riverview Apartments”
`floor_name`	RECOMMENDED	This field should contain the string name of the floor that the user should be placed in for a room assignment. This field is REQUIRED during room assignment creation or change, even if the user is not being moved across floors. Examples: “3rd Floor”, “3”, “Wing 3A”
`suite_name`	OPTIONAL	This field should contain the string name of the suite that the user should be placed in for a room assignment. (Note: This is an optional layer in the campus structure hierarchy that Roompact can represent). Example: “303-304”
`room_name`	RECOMMENDED	This field should contain the string name of the room that the user should be placed in for a room assignment. This field is REQUIRED during room assignment creation or change. Examples: “303”, “303A”, “402”

Note: Room assignment fields such as floor_name, and building_name act both as location keys for roster updates as well as user-facing labels within the application. If user-facing labels that differ from location keys are desired, they can be configured by a Roompact technical staff member.

OTHER INFORMATION

Please include a username and host/port when sending login information to Roompact (if sftp is used). Both password and key based authentication methods are supported for sftp. You can download Roompact’s public SSH key.