Resident Import API | Version 2.0

Return to Index

OVERVIEW

The Roompact User Synchronization API allows for the updating of Roompact resident account information by third parties. The API accepts batches of resident data in JSON format and updates the corresponding users in the Roompact system. Roompact will provide each third party that interfaces with the API a client key that will be passed to the API with each request.

Contents

SUBMITTING REQUESTS

All resident data sent to the Roompact API should be sent via the following Method/URL:

POST https://roompact.com/api/users

The Roompact server will respond in JSON format to any request submitted to this URL, even if the data sent with the request is not in a valid format or if the key is invalid. Each response object will contain a “status” field which will contain either SUCCESS or ERROR, and will include a “message” field giving more detail.

Successful Response

{
  "status": "SUCCESS",
  "message": "Request received"
}

Error Response

{
  "status": "ERROR",
  "message": "Could not read your API key - Perhaps your JSON string is incorrectly formatted?"
}

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.

JSON DATA FORMAT

The format that each request should adhere to is as follows:

{
  "key": "Elxob3Oiof1enbVNOxELygMMNafYI24nnCMyFAR4PTjc4f0TMFElWq7JBmHkpMHM",
  "version": "2.0",
  "user_data": [
    {
     	// The data of the first user to be updated
     	"user_email": "dmarks@roompact.com",
     	"user_first": "Danny",
     	"user_last": "Marks",
     	"user_phone": "1234567890",
    	"user_gender": "male",
    	"user_student_id": "1111222200",
    	"user_address": "123 S. Florida Ave, Suite 303, Chicago, IL 60606",
        "user_start_date": "2020-08-15",
        "user_end_date": "2021-05-01",
        "user_welcome_email_date": "2020-08-22",
    	"building_name": "Lincoln Hall",
    	"floor_name": "3rd Floor",
    	"room_name": "303"
    },
    {
     	// The data of the second user to be updated
     	"user_email": "jstevens@roompact.com",
     	"user_first": "Jack",
     	"user_last": "Stevens",
     	"user_phone": "1234562340",
    	"user_gender": "male",
    	"user_student_id": "1113444401",
    	"user_address": "500 N. Virginia Ave, Suite 40, Chicago, IL 60606",
        "user_start_date": "2020-08-15",
        "user_end_date": "2021-05-01",
        "user_welcome_email_date": "2020-08-22",
    	"building_name": "Jackson Hall",
    	"floor_name": "1st Floor",
    	"room_name": "105"
    }
    // Additional users can be included here
  ]
}

There are a few key aspects of the format that should be recognized:

API USAGE CONSTRAINTS

The Roompact API is robust in that it can accept different types of resident data in the form of varying fields and can also accept varying numbers of residents per request. However, there are a few limitations. Keep in mind the following:

UPDATE FREQUENCY

The recommended use for this API is to create a script that sends large batches of users en masse at a particular time of day. In this configuration a script will retrieve all resident data from the database or other software system, create data batch(es) that adhere to the API format and max request sizes, and send the request(s) at once. Under this scheme, optional fields could be included daily, even when unchanged. Applying this nightly technique when sending large BLOBs of image data is not recommended, and it is instead preferable to send image data fields only when an image is changed and must be updated, or once every few weeks.

In the event of a gap in updates (e.g. for a break between the Fall and Spring terms), the system will seamlessly resume processing data. All user accounts will be updated as defined in the following section.

USER UPDATE BEHAVIOR

The Roompact system will update user accounts with the data received from a client while in the following manner:

EXAMPLE REQUESTS

We will provide a few more examples of different requests that are both correctly and incorrectly formatted in the next few sections.

Example 1

{
  "key": "Elxob3Oiof1enbVNOxELygMMNafYI24nnCMyFAR4PTjc4f0TMFElWq7JBmHkpMHM",
  "version": "2.0",
  "user_data": [
    {
    	"user_email": "dmarks@roompact.com",
    	"user_uid": "dmarks91",
    	"user_first": "Danny",
    	"user_last": "Marks",
    	"user_image_data": "dGhlcmVpc25vc3Bvbndmb3Fpbm……9pcW5md29pbnF3ZmtvcW53Zms="
    },
    {
    	"user_email": "jstevens@roompact.com",
    	"user_uid": "jstev231",
    	"user_first": "Jack",
    	"user_last": "Stevens",
    	"user_image_data": "ZmtxbGp3ZmxrcWp3ZmxranF3bC……xtd3Fmbm9mYWxrandma3F3cWY="
    }
  ]
}

RESULT: SUCCESS

Explanation: This type of request can be used to update user images. The user_email and user_uid fields are included for the purposes of identifying which user each image string of image data corresponds to. Note that the user_image_data field contains a base64 encoded string, and in this example we have shortened to contents of this field significantly.

Example 2

{
  "key": "Elxob3Oiof1enbVNOxELygMMNafYI24nnCMyFAR4PTjc4f0TMFElWq7JBmHkpMHM",
  "version": "2.0",
  "user_data": [
    {
    	"user_email": "dmarks@roompact.com",
    	"user_first": "Danny",
    	"user_last": "Marks",
    	"floor_name": "3rd Floor",
    	"suite_name": "303",
    	"room_name": "C"
    },
    {
    	"user_email": "jstevens@roompact.com",
    	"user_first": "Jack",
    	"user_last": "Stevens",
    	"floor_name": "1st Floor",
    	"suite_name": "401",
    	"room_name": "A"
    }
  ]
}

RESULT: ERROR

Explanation: This request is invalid because the building_name field is missing while other room assignment fields are included. The building_name field must always be included for each user during a room assignment update. Including this field would make this a valid request that would result in each user being moved to the room indicated.

Example 3

{
  "key": "Elxob3Oiof1enbVNOxELygMMNafYI24nnCMyFAR4PTjc4f0TMFElWq7JBmHkpMHM",
  "version": "2.0",
  "user_data": [
    {
     	"user_email": "dmarks@roompact.com",
     	"user_uid": "dmarks91",
     	"user_first": "Danny",
     	"user_last": "Marks",
     	"user_phone": "",
    	"user_gender": "",
    	"user_student_id": "",
    	"user_address": ""
    },
    {
     	"user_email": "jstevens@roompact.com",
     	"user_uid": "jstev231",
     	"user_first": "Jack",
     	"user_last": "Stevens",
     	"user_phone": "",
    	"user_gender": "",
    	"user_student_id": "",
    	"user_address": ""
    }
  ]
}

RESULT: SUCCESS

Explanation: Although this request includes empty strings for multiple fields for each user, this request is valid. The result of this request would be to update the corresponding users to erase all of the data from the included fields.

Example 4

{
  "key": "Elxob3Oiof1enbVNOxELygMMNafYI24nnCMyFAR4PTjc4f0TMFElWq7JBmHkpMHM",
  "version": "2.0",
  "user_data": [
    {
        "user_email": "dmarks2@roompact.com",
        "user_uid": "dmarks91",
        "user_first": "Danny",
        "user_last": "Marks"
    },
    {
        "user_email": "jstevens2@roompact.com",
        "user_uid": "jstev231",
        "user_first": "Jack",
        "user_last": "Stevens"
    }
  ]
}

RESULT: SUCCESS

Explanation: It may seem that this request is doing nothing, but the Roompact system will look up each user based off of the user_uid field and change each user’s email address, first name, and last name to the contents of the user_email, user_first, and user_last fields, respectively. This is the type of request that a third party would send in order to change existing users’ email addresses or names (along with any other fields that need updating for the user).