People Finder

People Finder is a service that searches the SPIRE directory for people affiliated with UMass. This includes students, faculty, and staff, as well as some retirees who have opted to continue being listed.

From People Finder, you can look up any UMass person’s full name and school email address. Additionally, you can look up any student’s majors and degree program. You may also find any faculty or staff member’s title and department affiliation. If they have chosen to list it you may also find their phone number, physical office location, and homepage.

API information

The main endpoint for the Person Finder API is www.umass.edu/peoplefinder/engine/. This endpoint only takes POST requests, and will fail with HTTP error 405 on any other request type. It requires two parameters, and accepts several other optional ones. The first is q, your search query. The second is time, the time of the request in milliseconds since the UNIX epoch as an integer.

Note

The People Finder source code does reference and use other POST request parameters that aren’t documented here yet. We’ll get around to those someday.

Response format

Upon a successful request, the People Finder API will return a JSON response containing information on matching people. The basic format of the response is as follows:

{
 'ErrorCode': integer,
 'ErrorHint': string,
 'ErrorMsg': string,
 'OverflowFlag': boolean,
 'Results': array
}

The non-error values are 0 for ErrorCode, and a blank string ('') for both ErrorHint and ErrorMsg. I’ve not been able to trigger an error yet so I can’t say for sure what happens when there’s an error, but I think the field names are pretty self-explanatory.

The OverflowFlag field indicates whether there are more results for the query than are listed in the results. Information on a maximum of 13 people per query can be returned. If the overflow flag is set to true, be aware that there are more matching results than are being given to you. There is no way to paginate or get a different set of 13 people with the same query, so if you didn’t find the person you’re looking for, you’ll just have to try something else.

Tip

This 13 person limit doesn’t happen with the UMass Directory on SPIRE.

The Results field contains all the student data you’re looking for. It is an array of objects representing students. Fields are only included in the objects if they have values. Possible fields include:

  • Name: String of the person’s full name. Not split into first and last names, even though that’s how you enter it into SPIRE.

  • Email: String of the person’s school email. Generally @umass.edu, but graduate students and faculty often have email addresses for their specific departments. For example, computer science people usually have @cs.umass.edu emails.

  • Affil: Array of strings detailing the person’s affiliations to the university. It is possible to have more than one. Possible values include Student and Employee.

  • Major: Array of strings of the person’s majors and degree plans. Strings will usually be in the format of SUBJECT ([DEGREE]). Examples include Computer Science (BS) or Economics (PhD). This is not always the case. Here are some real major strings I’ve discovered that do not follow the usual format.

    • U. Without Walls OffCampus (Non Degree)
    • Part-Time MBA
    • Professional MBA (NonDeg) (WTF?!)
  • Vcard: The People Finder API also generates VCards! Throw the string in this field onto the end of www.umass.edu and you’ve got yourself a VCard.

  • Title: String of the person’s title at UMass. Employees only.

  • Phone: Array of strings containing phone numbers. Employees only.

  • Building: Array of strings detailing where the person can be found. I’m guessing that users are free to enter whatever they please here, as the level of detail varies greatly between people. Employees only.

  • Dept: Array of strings representing the departments the person is affiliated with. Employees only.

  • URL: Array of strings of URLs to the person’s personal websites. Employees only.

Reverse engineering tips

The information on this page was found from the People Finder’s JavaScript source code. There’s still stuff in there that’s not documented on this page yet. Most of the interesting stuff is happing in the pf_search function, found at around line 400-ish.