Retrieve Legacy Faculty180 Vitas in Bulk via API
This API recipe applies only to legacy Faculty180 standardized institutional Vita. It does not retrieve legacy personal Vitas or Vitas created with the new Vita Builder. New Vita Builder Vitas can be exported through the Vita Builder interface as PDF or Word files or shared using a shareable link.
Faculty Vitas are commonly used to communicate faculty activities, accomplishments, and credentials. In Faculty Activity Reporting (FAR, Faculty180), administrators can configure legacy standardized institutional Vitas to organize, group, and filter faculty data for different reporting purposes. The Vitas and their associated activities can then be retrieved through the Faculty180 Vita API. These API endpoints support two primary uses:
- Retrieve a formatted Vita for use outside FAR with the
output=htmloroutput=html_cleanparameter. - Retrieve the structured activity data included in a configured Vita with the
output=jsonparameter.
The output=json parameter returns the Vita’s activities as structured, fielded JSON data for use in other applications. To identify the sections and fields that may be returned for a particular Vita, call the Retrieve details of all vitae endpoint with the data=detailed parameter. This returns the sections and associated activity fields configured for that Vita.
Because the API output is based on the Vita’s configuration in FAR, nontechnical administrators can control what an automated process retrieves by updating the Vita in the FAR interface. Institutions can configure multiple legacy institutional Vitas for different reporting needs and retrieve any of them through these endpoints.
Each request requires a vitaID. This ID is not displayed in the FAR interface and must be obtained by searching for the Vita through the API. The search can use the Vita’s title or owning unit. Give each institutional Vita a unique, descriptive title so it can be identified reliably.
Each retrieved Vita belongs to one faculty member. The request must therefore also include that faculty member’s FAR userid, which can be obtained through the 'users' endpoint. To retrieve Vitas for multiple faculty members, call the endpoint separately for each faculty member.
Use the termstart and termfinish parameters to define the activity period included in the Vita. If these parameters are omitted, the endpoint returns activities from the current term by default.
Check out the Vita API documentation for more information.
Retrieve FAR Vitas for Multiple Faculty via API
This API retrieves only legacy standardized institutional Vitas. It does not retrieve legacy personal Vitas created by individual faculty members or Vitas created with the new Vita Builder.
Retrieve details of all vitas (get a list of vitas)
Action: GET => /vitas
Required Parameters: None
Optional Parameters: “q”, “unitid”, “data”
q: string - This optional parameter allows for the inclusion of a query string that will search the titles of all the configured standardized vitas and return any that have a match to the query string. A wild card “*”, asterisk, character can be used in the query string.
unitid: integer - Providing a legitimate unitid specifies that the returned list of vitas should be only those owned by the unit specified. Unit IDs can be found using the units endpoint: “/units”.
This endpoint is a necessary first step in retrieving vitas via the API. Calling it and finding the appropriate vita in the returned list is the only way to know the “vitaID” that is necessary for all later calls.
Check out this article on Building and Managing Your Organizational Structure for more information.
Note that it is acceptable to send a comma-separated list of unitids as the parameter value.
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 vita ID is sought, then “summary” is sufficient. The “detailed” option also returns the complete list of data sections that each returned vita is configured to display.
Retrieve details for a user’s vita
Action: GET => /vitas/{vitaid}/{userid}
Required Parameters: “vitaid”, “userid”
Suggested Parameters: “output”, “termstart”, “termfinish”
output - string - This determines how the vita’s data will be returned. The options are: “json”, “html”, “html_clean”. The JSON and “html_clean” output return the activity data contained within the vita with no formatting. The “html_clean”, delivered HTML without formatting is designed to be a delivered option that allows for immediate easy use with the institution's own stylesheets applied for formatting. The “html” output delivers the formatted HTML vita document/page exactly as it would have been delivered within the FAR user interface, with all formatting intact.
termstart & termfinish - string - A vita is a list of activities that occurred within a given time frame, so these two parameters are important to determine the list of activities that will be shown based upon what start term and end term are specified. To see a list of terms and their associated termids (the required parameter value) you can use the Faculty Activity Reporting terms API endpoint. The default for either of these parameters, if they are not given, is the current term.
FAQs
Why does the /vitas API return no Vita?
Confirm which Vita experience was used to create the Vita. The /vitas API documented here returns only legacy Faculty180 standardized institutional Vitas. It does not return legacy personal Vitas or Vitas created with the new Vita Builder. New Vita Builder Vitas must be exported through the Vita Builder interface.