API Documentation | Hosted CSV Roster

Return to Index

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_gender
user_student_id
user_address
user_birthdate
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.

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_gender OPTIONAL The user’s gender. Male can be represented as “m” or “male” and female can be represented as “f” or “female”. Any other input will be coded as “non-binary”. This field is case insensitive.
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_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.