Download Candidate Application Documents via the API
Overview
Many systems on campus might be involved in the workflow for hiring and onboarding a new faculty or staff member. When interacting with these other systems, it may be valuable to have all of the materials that a candidate submitted for a position in Faculty Search available for review. For example, you may need to pull documents from a successful candidate to load into your HR or ERP system (documents like their vita or submitted transcripts). Appropriate candidates can be identified, and any documents and media files they submitted with their application(s) through the Faculty Search API can be downloaded. Using this API would facilitate the automation of the “onboarding” of recently hired faculty members into the institution’s HR or ERP systems.
Prerequisites
The institution will need to have populated their Faculty Search implementation with appropriate positions, and these positions must require candidate submission of the documents that the institution is interested in tracking and using outside of Faculty Search. Candidates must have applied to these positions and submitted the appropriate documentation. Finally, in order to select the appropriate candidates, all workflow steps should be followed in Faculty Search to mark candidate statuses appropriately as candidates progress through the workflow. (In the API, candidates who were successfully hired cannot be properly identified unless they were marked as such in Faculty Search.)
Using the API
In order to utilize the API resources and download final documents, the script has to “walk” the Faculty Search API endpoints. First, appropriate positions need to be identified and position IDs obtained. With appropriate position IDs, the relevant applicants/candidates for those positions should be identified and the applicant IDs stored. Now for each identified application, there is a collection of documents. The appropriate documents needed should be identified, and then each document can be downloaded via the URL returned by the API.
API Resources Available
| Resource | Description |
|---|---|
| Retrieve Positions |
The positions#index endpoint will return all searched positions at your Institution. The key data returned here is the “id” for each position. This value will be used in subsequent API calls. Action: GET => /byc-search/{tenant_id}/positions Required Parameters: “tenant_id” (path) Optional Parameters: “archived”, “open” (boolean, path query) |
| Pagination Features |
This action will return all positions that are open and not archived. Example: GET => /positions?open=true&archived=false |
| Retrieve Applications |
The applications#index endpoint will return all applications for a given position. You can optionally include the “archived” boolean parameter to return all applications where “archived=false” or “archived=true”. The key data returned here is the “id” for each application. This value will be used in subsequent API calls. Action: GET => /byc-search/{tenant_id}/positions/{position_id}/applications Required Parameters: “tenant_id”, “position_id” (path) Optional Parameter: “archived” (boolean, path query) |
| Retrieve Application Document Data |
The applications#document_data endpoint will return info for all documents and media associated with a submitted application. The key data returned here are the attributes “id”, “format”, “downloadable”, “details”, and “url”. The “id” will help you keep track of which files you have retrieved. The “format” will be either “PDF”, “IMAGE”, “LINK”, “VIDEO”, or “FORM_RESPONSES”. Media objects that have “PDF” or “IMAGE” are downloadable directly from Interfolio’s API. Media with “LINK” or “VIDEO” will have “url” values that point you to an external web address. Media with the “FORM_RESPONSES” format represent a PDF generated by Interfolio of form responses submitted by the applicant. The attribute “downloadable” will indicate if a “PDF” or “IMAGE” is available for download. The “details” node will contain two more key pieces of data, “title” and “type.” This node is useful for identifying specific document types that you want to retrieve. For instance, if you want to retrieve only C.V.s, you can iterate through the list of application media, downloading only media with “details” => “type”: “C.V.”. Finally, the “url” value will be the endpoint where you can retrieve the “PDF” or “IMAGE” or access the application “LINK” or “VIDEO.” Action: Required Parameters: “tenant_id”, “position_id”, “application_id” (path) For application media with a format of “PDF” or “IMAGE”, the “url” returned by the applications#document_data endpoint will contain an endpoint that looks like this: Example: GET => /byc-search/111/positions/222/applications/333/documents/444\ In response to this GET, the API will respond with a 302 status and a “location” header. This header will contain a temporary redirect URL where the file can be found. Depending on the method that you use to make REST API calls, your API client will likely follow this redirect by default. You will need to disable redirects and capture the value for the “location” header. Once you have that value, you can run another GET call to that URL. The API will respond by streaming the file directly to you. |
Check out this detailed API documentation for more information.