User Provisioning and Management in Faculty Activity Reporting via the API
Institutions need a reliable process for managing faculty and staff access to Interfolio’s Faculty Activity Reporting (FAR). Timely removal of access for users leaving an institution and efficient updates for existing users are critical for security and accuracy. Automating these processes via a FAR API, especially when paired with Single Sign-On (SSO), reduces manual workload and eliminates delays that can prevent faculty from accessing tools promptly.
Prerequisites
Before managing faculty accounts through the FAR API, ensure the following data elements are available:
- userid (Faculty ID)
- email address, primary unitid, employment status, and faculty name
- tenant_id and personal identifier (PID): Can be found via API endpoints using the institutionally assigned userid/faculty id.
- unitid: Identifies the primary academic unit for the faculty member. Retrieve via the “units” api endpoint.
The FAR API uses HMAC authentication for some resources. Ensure your integration supports this method.
Provision and Manage Users
Managing user accounts via the FAR API consists of 2 main tasks:
- Updating data in existing user accounts
- De-provisioning, i.e. removing login rights from user accounts.
Creating new faculty records via the FAR API is not supported. For new user creation or large-scale provisioning, contact your Customer Success Manager (CSM), Account Manager (AM), or Project Manager (PM).
In order to complete these tasks effectively there are a number of data elements that should be fully understood. These fields are:
| Field | Description |
|---|---|
| userid (called the “Faculty Id” in the FAR software interface) | This is the primary Faculty identifier required and used throughout these API endpoints to identify faculty. It is an identifier which is assigned by the institution |
| PID (Personal Identification) | This is an Interfolio assigned identifier used across our entire Faculty Information System suite of software. It is needed for those few endpoints that assist in managing the linkages across the software suite. The PID for a faculty member is retrievable through the API using the /users/{userid} endpoint with the data=detailed parameter. |
| tenant_id | This is the Interfolio-assigned numerical identifier for your institutional database. This number is required for all endpoints that utilize the newer HMAC API authentication system. |
| employmentstatus | This is a fundamental Faculty Classification in FAR. Failing to provide a proper value to this parameter can result in confusion for administrators in the software trying to manage and report on faculty. The default values allowed are: “Full Time”, “Part Time”, “Staff”, “Inactive”. |
| primaryunit | This is a fundamental faculty attribute in FAR which specifies the unitid of the primary academic unit that a faculty is assigned to. Failing to provide a proper value to this parameter can result in confusion for administrators in the software trying to manage and report on faculty. The unitid of any given unit can be found via the /units API endpoint. |
| sendemail | This is an optional boolean parameter that controls whether a welcome email is sent to the faculty after their account is created. The default, if this parameter is not included/specified is to not send the faculty member an email upon account creation. If the boolean value of “true”, or 1, is sent a welcome email will be sent to the email address specified in the required “email” field (or that on file if a PID is specified for an existing account in another Interfolio software product.) |
The FAR API supports two automated user management tasks: provisioning existing accounts and de-provisioning access. Provisioning is handled through two methods:
- Subscribe endpoint: Use this when the user already has an Interfolio account in the Faculty Information System (FIS) suite. This ensures the FAR account is linked to the existing profile.
- CSV bulk subscribe endpoints: Use this when adding multiple users in bulk from a flat-file format such as CSV.
De-provisioning users is a two-step process:
- Remove login access by using the unsubscribe endpoint.
- Update the user’s employment status to “Inactive” so their status is accurately reflected in FAR.
To remove the ability of a faculty member to log in to FAR, they must be “unsubscribed” using the unsubscribe endpoint.
API Resources Available
| Resource | Description |
|---|---|
| Retrieve a listing of users with basic identifying information |
Action: GET => /users Required Parameters: None Optional Parameters: q, unitid, employmentstatus, data q: string This optional parameter allows for the inclusion of a query string that will search the three name fields (first, last and middle) of all user accounts and return any that have a match to the query string. The underlying query engine does partial substring matching, and a wild card, asterisk, character can be used in the query string. unitid: integer Providing a legitimate unitid specifies that the returned list of faculty should be only those assigned to the unit specified (or any of its sub-units). Unit IDs can be found using the units endpoint: “/units”. (Also, see the recipe on “Building and Managing Your Organizational Structure”.) It is acceptable to send a comma-separated list of unitids as the parameters value. employmentstatus: string The Employment Status is a fundamental Faculty Classification in FAR, and is often the first default filter that is used in sorting through a list of faculty. Using this parameter will limit the list of returned faculty to only those whose employment status is set to one of the proscribed values that is sent. The default values allowed are: “Full Time”, “Part Time”, “Staff”, “Inactive”. data: string A standard parameter found in all FAR GET endpoints which specifies the level of detail that should be returned. Valid values are: “count”, “summary”, and “detailed”. The default value, if none is specified, is “count”. If just the faculty userid is sought then “summary” is sufficient, but if the “PID” is required it is only returned in the “detailed” data. This endpoint is an important first step in managing existing users via the API. Calling it and finding the appropriate user in the returned list is the only way to know the “userid” and/or “PID” that is necessary for all later calls. |
| Subscribe a user to FAR |
Requires HMACs authentication Action: POST => /fars/{tenant_id}/users/{pid}/subscribe Required Parameters: tenant_id, PID in the path Optional Parameter: None If the faculty member being added to FAR is already a provisioned user in another software in the Interfolio Faculty Information System suite of products then this “subscribe” API endpoint can simultaneously add them as a new FAR user and link their account to the established account in another software. The identifying “firstname”, “lastname” and “email” fields are not sent with this request because they are pulled using the PID provided. The remaining “required” fields of institutional “userid”, primary assigned unit unitid (primaryunit), and “employmentstatus” should be sent in order to properly create the user in FAR. |
| Update the details of an existing user |
Action: PUT => endpoint /users/{userid} Required Parameters: userid in the URL path Optional Parameter: none Any data values sent will overwrite existing values in the system. Note: Changing a user accounts “employmentstatus” to “Inactive” is not sufficient to “deprovision” their account and stop their login privileges. In order to stop a user account’s login privileges the “Unsubscribe a user” endpoint must be used. |
| Unsubscribe a user from FAR |
Requires HMACs authentication Action: PUT => /fars/{tenant_id}/users/{pid}/unsubscribe Required Parameters: tenant_id, PID in the path Optional Parameter: None Submitting to this endpoint will remove the ability of the user designated by the submitted pid from logging into FAR. This will not affect the data fields (such as employment status) in FAR. In order to update that data the “updates existing user” endpoint has to be used. |
| Subscribe and/or Update multiple users using a CSV file |
Requires HMACs authentication Action: POST => /fars/{tenant_id}/users/csv_create Action: POST => /fars/{tenant_id}/users/csv_update Required Parameters: tenant_id in the url path Optional Parameter: None Subscribe and Update user endpoints this endpoint takes the same fields sent in bulk in CSV format. The CSV file must be uploaded as a part of the request. The CSV file must be formatted to have a header row indicating the correct names of the data fields sent and each row represents the data for a given user account. The required fields for each faculty record are the same as those for the Update Existing User endpoints, as appropriate. The user identifier sent is the FAR userid. |