Resident Assignment 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
• Data Fields
• JSON Data Format
• Usage Constraints
• Update Frequency
• User Update Behavior
• Example Requests

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.

• 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.

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:

• The key field must be included at the outermost level of the request, and should contain the API key that Roompact provides.
• The version field must be set to a value of 2.0.
• The user_data field is an array that contains the bulk of the data of each request.
• Each block within the array represents a user to be updated. It is here that the mandatory fields (such as user_email) must be included for each user.

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:

• There is no limit on request size in terms of number of users. The examples in the Example Requests section below include two users per request.
• The Roompact servers have a hard limit of 100MB per HTTP request, requests larger than this will be automatically rejected. Requests that contain the user_image_data field (base64-encoded image BLOBs) have the potential to reach this size limit. In the case of such an update, multiple significantly smaller requests should be sent in place of each large request.
• For the sake of application performance, third party data submitted to the API is not processed immediately but stored until lower traffic times. Processing begins daily at 2:30 AM CST (UTC -6:00). This means data to the API on a given day will not be reflected in the system until the following morning.

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:

• New users with start/end dates supplied that do not have Roompact accounts will have accounts created and given a room assignment according to the dates specified.
• New users with NO dates supplied that do not have Roompact accounts will have accounts created and be assigned to their designated room assignments immediately.
• Existing users will be updated in accordance with the data supplied for them (including basic user information as well as room assignments). The user_email field will only be updated if the user_uid field is also provided. The user_uid field can never be changed for a given user.
• Omitted users with start/end dates set for existing room assignments not be affected when omitted.
• Omitted users with NO dates set for existing room assignments will have their accounts disabled and archived, with their room assignment end date set to the date preceding the data import.
• Duplicate users (users included multiple times in a batch of data) will be updated in accordance with the first entry in the batch. Subsequent entries for the same user will be ignored.

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).