UC Recruit provides a RESTful web service to expose the waivers stored in the system. This is a read-only API that allows consumption of the data for integration into other systems for analytics, tracking, and reporting.
If you would like access to the API, please fill out the form here. This form helps us maintain control over who has access to the API and the information contained within.
Working with the API
Requests listed below are prefixed with their necessary HTTP verb.
Making Valid Requests
All requests should use the GET HTTP method. All API requests require HTTP Basic Authentication. Please see your systems administrator for assistance in determining the username and password for your site, or contact UCRecruit-Support@uci.edu. It is strongly suggested that the following headers be set, or that all requests use a .json suffix to ensure that JSON responses are generated.
- ‘Accept’ HTTP Header
-
application/json
Listing Waivers
To list the entire set of Waivers in a given Academic Year:
GET https://recruit.ucx.edu/api/v1/waivers?academic_year=2015%20-%202016
Note that the academic_year parameter must follow the format nnnn – nnnn. Whitespace is significant and required. Asking for years that the system does not know about will yield an empty list of Waivers. Asking without providing an Academic Year will result in a 400 response code. The following fields are present in a successful response:
Fields for waivers list |
Format | |
|---|---|---|
| meta.academic_year | The Academic Year that was requested. | /^\d{4} – \d{4}$/ |
| meta.as_of | A timestamp showing when the list was generated. | ISO 8601 “Combined date and time in UTC” format. Example: 2012-04-19T20:13Z |
| waivers | An array of waiver descriptions for the requested Academic Year. Contains subfields. | Object |
Once you have this information you can look at individual waivers using the next endpoint.
Fetching Individual Waiver Information
To obtain more information about an individual waiver with code SWR00123:
GET https://recruit.ucx.edu/api/v1/waivers/SWR00123
Asking for waivers that the system does not know about will yield a 404 response code. A valid response will return one JSON object representing the waiver.
Fields for waivers |
Format | |
|---|---|---|
| academic_year | The academic year in which this waiver was initiated. | /^\d{4} – \d{4}$/ |
| added_history | Any historical records that were added to this waiver. Contains subfields. | ; |
| affirmative_action_goals | The waiver’s selected affirmative action goals. | array of strings |
| appointment_start_date | The appointment start date for this waiver. | ISO 8601 date |
| appointments | An array of objects representing all appointments for this Waiver. Contains subfields. | Object |
| approval | The approval request for this Waiver. Contains subfields. | Object |
| approval_status | The status of the approval request for this Waiver. | Text |
| availability_cohort | The type of hire for this waiver (Tenured/SOE, other academic positions, etc.) | string |
| candidate | The candidate for whom the waiver was created Contains subfields. | Object or nil |
| candidate_hired | Indicates whether the candidate has been hired. | boolean |
| candidate_qualifications | The qualifications of the candidate for whom this waiver was created. | Text |
| category | The category of this search waiver Contains subfields. | Object |
| central_office_comments | The comments made between central offices, if you have permission to see them. Each element contains subfields. | Object |
| central_office_documents | Documents uploaded by central offices, if you have permission to see them. Each element contains subfields. | Object |
| code | The identifier you can use to refer to this search waiver request | Matches the regular expression /SWR(\d+)/ |
| concluded_at | A timestamp revealing when this waiver was concluded. | ISO 8601 date |
| created_at | The date that this waiver was created | ISO 8601 date |
| created_by_external_user_id | The external_user_id of the user who created the waiver. | text |
| declined_at | The date that the waiver was declined. | ISO 8601 date |
| declined_by_external_user_id | The external_user_id of the user who declined the waiver. | text |
| deleted_at | The date that the waiver was deleted. | ISO 8601 date |
| department | The home department for this Waiver. Contains subfields. | Object |
| discovered_history | Any historical records that share a connection with this waiver. These are automatically discovered based on their waiver’s employee ID and email addresses. Contains subfields. | array of objects |
| employee_id | The candidate employee ID for this waiver. | string |
| ends_on | The expiration date for the waiver. | ISO 8601 date |
| expiration_type | The type of expiration of the waiver (permanent or time limited). | string |
| final_decision_note | The note left for the final decision of the approval | text |
| grant | The Grant information associated with specific justification category of the waiver. Contains subfields. | Object |
| hiring_type | DEPRECATED; please use availability_cohort instead | string |
| justification_narrative | Narrative explanation detailing the reasons for the search waiver, and include details about why it is not possible to conduct an open search for the position. | Text |
| not_hired_explanation | An explanation why the candidate was not hired | Text |
| position_duties | The duties of this position along with associated areas of responsibility. | Text |
| position_working_title | The name of the position that the waiver seeks to fill. | text |
| salary_control | The salary control number if provided by the analyst when creating the Waiver. | string |
| school | The home school for this Waiver. Contains subfields. | Object |
| starts_on | The effective date for the waiver. | ISO 8601 date |
| updated_at | The date that this waiver was last changed. | ISO 8601 date |
| urls | The URLs at which more information about this waiver can be obtained.Contains subfields. | URL |
Fields for candidate |
||
| appointments | Appointments for the candidate. Contains subfields. | Object |
| current_employee | Indicates whether the candidate is a current employee. | boolean |
| current_position_started_at | The start date for the employee’s current position. | ISO0 8601 date |
| employee_id | The employee ID of the candidate. | text |
| name | The name of the candidate. | text |
| urls | The URLs at which more information about this candidate can be obtained. Contains subfields. | URL |
Fields for appointments |
||
| department | The appointment’s department. Contains subfields. | Object |
| description | Combination of the appointment’s title code and step. | text |
| ends_at | The appointment’s end date and time. | ISO0 8601 date |
| percent_time | The percent time for the appointment. | Integer |
| starts_at | The appointment’s start date and time. | ISO0 8601 date |
| step | The appointment’s step. | text |
| title | The title for the appointment. Contains subfields. | Object |
Fields for approval |
||
| approvers | The steps that this approval must take to be approved. Each element contains subfields. | Object |
| comments | The comments made on this approval. Each element contains subfields. | Object |
| created_at | When this approval was submitted | ISO8601 date |
| creator | The the user who submitted this approval request | Object |
| name | The name of this approval request | text |
| updated_at | When this approval was last modified. Includes comments added, approvers filled, and changes to the approved object. | ISO8601 date |
Fields for approvers |
||
| created_at | When this approver step was submitted. | ISO8601 date |
| filled_by_external_user_id | The external user id of the user who filled this step, if it is filled | text |
| name | The name of the step. Explains who can fill it. | text |
| required | Indicate whether this step is required or not. | boolean |
| updated_at | When this approval was last modified. | ISO8601 date |
Fields for category |
||
| name | The category name of this search waiver (Emergency Hire, Target of Excellence, etc.). | string |
| type | The type of search waiver (Senate Faculty, Non-senate Faculty and Other Academics, etc.). | string |
Fields for central office documents |
||
| comment | Comment made on the document | string |
| created_at | When this document was uploaded | ISO8601 date |
| description | The description of the document | string |
| filename | The filename of the document | string |
| updated_at | When this document was last modified | ISO8601 date |
Fields for comments |
||
| comment | The text of the comment. | text |
| created_at | The time that the comment was initially created. | ISO8601 date |
| external_user_id | The external_user_id of the user who made the comment. | text |
| updated_at | The time that the comment was last updated. | ISO8601 date |
Fields for department |
||
| external_id | The department’s external ID. | text |
| name | The department’s name. | text |
| tags | Tags associated with the department | Array of strings |
Fields for grant |
||
| funding_agency | Funding agency of the grant. | text |
| grant_number | Identification of the grant. | text |
| percent_time | The percent time for the grant. | Integer |
| salary | Salary amount for the grant. | Integer |
| urls | The URLs at which more information about this grant can be obtained. Contains subfields. | URL |
Fields for added history |
||
| approved | Indicates whether previous hire was approved. | boolean |
| candidate_name | Name of the candidate for whom the previous waiver was created. | text |
| category | The category of this search waiver or exemption Contains subfields. | Object |
| department | The department into which the hire was attempted. Contains subfields. | Object |
| ends_on | The date at which the previous appointment ended. | ISO0 8601 date |
| position | Position that the historical record sought to fill. | text |
| reference_number | Identifier; can be a JPF#, SWR#, EXR#, or something else. Not guaranteed to be unique | string |
| source_type | What kind of record this is. | string; one of Recruitment, Waiver, Exemption, or Other |
| starts_on | The date at which the previous appointment began. | ISO0 8601 date |
Fields for discovered history |
||
| department | The department into which the hire was attempted. Contains subfields. | Object |
| details | Additional information captured about the historical record. | Object; keys are labels suitable for display; values are all strings |
| identifiers | The bits of information used to identify the candidate. Contains subfields. | Array of objects |
| reference_number | Identifier; can be a JPF#, SWR#, or EXR# | string |
| school | The school into which the hire was attempted. Contains subfields. | Object |
| source_type | What kind of record this is. | string; one of Application, Waiver, or Exemption |
| status | What stage the historical record was in at time of last discovery. | string |
| title | A human-readable name that can identify this historical record. Should usually be paired with the reference_number for maximum clarity. |
string |
Fields for discovered history identifiers |
||
| type | What kind of identifier this is. Suitable for display. | string; one of Email address or Employee ID |
| value | The identifier itself. | string |
Fields for title |
||
| code | The waiver appointment title’s code. | Integer |
| name | The waiver appointment title’s name. | text |
Fields for school |
||
| abbreviation | Abbreviation of school | text |
| address | Address of school | text |
| external_id | External id of school | text |
| name | Name of school | text |
| tags | Tags associated with the school | Array of strings |
Fields for Candidate URLs |
||
| cv | The API URL to the CV of the candidate | string |
Fields for Grant URLs |
||
| documentation | The API URL to the grant documentation | string |
Fields for Waiver URLs |
||
| api | The API URL of the waiver | string |