Dartmouth API Developer Portal

Employees API

Returns information about employees at Dartmouth College.

Rating

Attribute Value
Highly Available Yes
Cache Refresh Interval Hourly
Filtering Yes

Required Scopes

Scope Description
"urn:dartmouth:employees:read.sensitive" This scope is required in order to view employee information. Authorization of this scope is granted by the HR Office

Request

GET /api/employees/{netid}

Required Headers

Authorization: Bearer {jwt}

Parameters

Parameter Name Type Description Valid values Required

(none)

Notes on usage

The scope associated with this resource allows the calling individual/application access to "confidential" employees when requested. The calling individual/application must adhere to Dartmouth's policies on data privacy when using this data.

The employees API is designed to return information about current active employees or future employees. The API does not provide historical information about past positions and jobs.

The API provides information in a nested hierarchical structure. At the first level are attributes for the employee regardless of particular appointments or jobs. At the second level is an array of jobs that provide all the details about an employee's various jobs and appointments. Also at the second level is a structure called faculty_data which will have rank and tenure information for faculty.

The employees API is availble for filtering and paged result sets consistent with the syntax specified in the introduction section covering filtering and paging.

Termination data is only available ExEmployees during the 18 month ExEmployee assignment status. Termination may not be available for Emeriti in ExEmployee status.

Returns

Status Code Description
200 The URI parameter {netid} passed in is a valid employee
404 The URI parameter {netid} passed in is NOT a valid employee

Top Level Payload Attribute Descriptions

Field Type Sample Data Description Known Issues Required Scope
cache_date string 2016-01-01T05:00:00Z the last update of the cache for this record in iso8601 format urn:dartmouth:employees:read.sensitive
home_department string Human Resources Operations the organization considered the home department for the employee, deprecated in favor of the is_home_department attribute in the jobs structure urn:dartmouth:employees:read.sensitive
jobs array an array of all current jobs as of today for the employee (see attributes in next table) urn:dartmouth:employees:read.sensitive
faculty_data array an array of faculty appointments by organization (see attributes in next table) urn:dartmouth:employees:read.sensitive
netid string d33961y netid of the employee urn:dartmouth:employees:read.sensitive
person_type array Employee broadest categorization of person, only Employees are paid through Dartmouth College (see additional notes below) Values are: Employee, ExEmployee or Non-Paid urn:dartmouth:employees:read.sensitive
primary_payroll string Monthly Monthly, Biweekly Staff (as opposed to Biweekly Student), or Non-Paid urn:dartmouth:employees:read.sensitive
i9_date string 2020-08-22T04:00:00Z expiration date of person's current i9 which is the last date for eligibility to work in the US, null for anyone with a non-expiring i9 urn:dartmouth:employees:read.sensitive
i9_status string Yes this field will contain values detailed in the table below urn:dartmouth:employees:read.sensitive
is_benefits_eligible boolean true employee qualifies for benefits under college policy documented by this link urn:dartmouth:employees:read.sensitive
is_med_enrolled boolean false The individual is enrolled in Dartmouth’s employee group health plan urn:dartmouth:employees:read.sensitive
emeritus_data object see detailed description below for this object urn:dartmouth:employees:read.sensitive
schedule_data object an array of schedule data as of today for the employee (see attributes in next table) object urn:dartmouth:employees:read.sensitive
last_date_employed string 2021-08-31T04:00:00Z date last employed in ISO8601 format, populated for ExEmployees
last_date_paid string date last paid in ISO8601 format,last date paid within the current period of service for any employee or ex-employee in the past 18 months, will be null for Non-Paid employees

Detailed descriptions for i9_status

Value Description
Waived The individual was hired prior to the federal requirement to complete an I-9.
Expired The individual’s I-9 (employment eligibility) has expired.
Non-Paid The individual is Non-Paid. An I-9 is not required.
Non-US Location The individual is working in a Non-US Location. An I-9 is not required.
Not Entered An I-9 has not yet been completed.
Pending (HR USE ONLY) HR is actively working with the Employee to obtain the I-9.
No No valid I-9 is on file.
Yes A valid I-9 is on file
Faculty Not Here Yet (invalid value)

Detailed descriptions for emeritus_data

Value Type Sample Data Description Known Issues
salutation string
year_of_appointment string
emeritus_title string
email_after_termination string
status_grant_year string
status_grant_month string
emeritus_organization string

Jobs Structure

Field Type Sample Data Description Known Issues
assignment_number string the assignment number coding for the job
location object the location information for the employee
is_home_department boolean true true if this is the home department job of the employee, false otherwise
job_base_status string Regular Regular, Temporary or Non-Paid as defined under HR policy https://www.dartmouth.edu/~hrs/pdfs/employment_status.pdf
job_current_status string Active Active or Inactive. Records with ExEmployee person_type are considered Inactive as are records for Employee person_types when the individual is on a leave
job_end_date string 2024-30-06T04:00:00Z end date of the job in iso8601 date format, null if there is no end date for the job
job_group string Staff Faculty or Staff. Faculty includes job_type Faculty, Fellow, Non-Paid, Research Associate A, Research Associate B, Research Associate C. Staff includes job-type Exempt Staff, IATSE, Non-Exempt Staff, Non-Union Service, SEIU
job_start_date string 2016-01-01T05:00:00Z the start date of the job as of the last status change (see original_job_start_date)
job_type string Exempt Staff The employment group for that job record. Faculty, Fellow, Non-Paid, Research Associate A, Research Associate B, Research Associate C, Exempt Staff, IATSE, Non-Exempt Staff, Non-Union Service, SEIU
job_organization object the organizational structure which this job belongs to
original_job_start_date string 2016-01-01T05:00:00Z The date this position_title first appeared for this person The query for determining this value accurately is still under construction
payroll_type string Monthly Monthly or Biweekly Staff, only applies to paid record
position_title string Executive Director, HR Services Position title
supervisor_netid string f0029x1 unique id for supervisor of that job record
maintenance_crew object crew and shift that this job belongs to

Jobs Organization Structure

Field Type Sample Data Description Known Issues
academic_division string Human Resources Defaulted to sub_division for non A&S organizations
department string Human Resources Operations Organization designated as Department in the HR Org Hierarchy based on this record's home_department
division string Finance and Admin Organization designated as Division in the HR Org Hierarchy based on this record's home_department
id string 5bbe5ff0129f9a5a96149102 the object id for the organization structure. This id can be followed to the /human_resources/organizations API
organization string Human Resources Operations the organizational structure which this job belongs to
organization_namespace string human_resources Human Recources as the source of the information
sub_division_or_school string Human Resources Organization designated as the subdivsion or school in the HR Org Hierarchy based on this record's home_departmental
subunit string Human Resources Operations Organization designated as Subunit in the HR Org Hierarchy based on this record's home_department
unit string Human Resources Operations Organization designated as unit in the HR Org Hierarchy based on this record's home_department

Jobs Location Structure

Field Type Sample Data Description Known Issues
description string 4 Currier Place, Room 233AD the description of the location
building_id string 1486 building id fed from space system to hr_locations.attribute19 some entries appear to be invalid and must be researched further
space_id string 233AD space id fed from space system to hr_locations.attribute18 some entries appear to be invalid and must be researched further

Jobs Maintence Crew Structure

Field Type Sample Data Description Known Issues
crew_code string JD the crew this job belongs to
crew_shift string 1B the shift this job belongs as of today
shop_lead boolean true if the employee is shop lead or not, applicable to the primary position

Work Schedule Structure

Field Type Sample Data Description Known Issues
start_time string 06:00 the crew this job belongs to
end_time string 14:30 the shift this job belongs as of today

Faculty Data Structure

Field Type Sample Data Description Known Issues
as_of_indicator string Today Most faculty appointments are as of the current day indicated by Today, future appointments will say Future - yyyy-mm-dd and date of future appointment
organization object the organization attached to this faculty appointment, refer to substructure documentation for oranization information above
faculty_rank_code string 10 See descriptions below
faculty_rank_description string Professor See descriptions below
faculty_rank_rank_date string 1998-07-01T04:00:00Z The date the individual attained the rank noted.
faculty_rank_status string See descriptions below
tenure_code string NT DMSC See descriptions below
tenure_description string See descriptions below
tenure_tenure_date string The date the individual attained the Tenure Code noted.
tenure_asst_prof_start_term string 202009 Term code when rank of assistant professor started.

Schedule Data Structure

Field Type Sample Data Description Known Issues
work_schedule object start and end times as of today for the employee - refer to substructure documentation for work schedule above
scheduled_daysoff array ["SUN","SAT"] an array of all scheduled days off as of today for the employee

Additional Notes on Attributes

person_type

The person_type attribute describes in a single attribute the standing of the person from an HR perspective. The structure currently allows for an array of values to manage future use cases where an Employee may be in more than one classification at at time, for example an existing Employee could also be an Applicant for a new position. The values for this attribute are:

Value Description
Employee Currently an active employee in an active job. All Employees are paid by Dartmouth College
ExEmployee Was an employee of Dartmouth and now has terminated and has an Inactive status for 18 months post termination date to support access to online W2s
Non-Paid Non-Paid faculty appointments are the typical example of this type

primary_payroll

This attribute is determined by examining all the jobs for the Employee and returns the Payroll (whether Monthly, Biweekly Staff, or Student) of the job with the highest FTE allocation.

is_home_department

Home department is the organization to which the person has chosen to be affiliated.

job_group

The job group is the broadest categorization of the employee. Job Group combines a number job types into Faculty or Staff. Faculty includes job_type Faculty, Fellow, Non-Paid, Research Associate A, Research Associate B, Research Associate C Staff includes job-type Exempt Staff, IATSE, Non-Exempt Staff, Non-Union Service, SEIU.

job_type

The job_type attribute is indication of the employment group of the employee. Only paid employees are assigned a job type. The following are the possible values:

Value Description
Exempt Staff exempt staff
Faculty
Non Exempt Staff
SEIU
Research Assoc B/C
Fellow
Exempt Student
Non Exempt Student
IATSE

Faculty here does not include Research Associates.

faculty_rank code and descriptions

Value Description
10 Professor
11 Professor of Clinical
12 Adj Prof of Clinical
13 Visiting Professor
14 Professor in Residence
15 Adjunct Professor
16 Research Professor
18 Instructional Professor
19 Visiting Research Professor
20 Associate Professor
21 Assoc Prof of Clinical
22 Adj Assoc Prof of Clinical
23 Visiting Assoc Professor
25 Adjunct Associate Professor
26 Research Assoc Professor
28 Instructional Associate Professor
29 Visiting Research Assoc Prof
30 Assistant Professor
31 Asst Prof of Clinical
32 Adj Asst Prof of Clinical
33 Visiting Asst Professor
34 Visiting Asst Prof of Clinical
35 Adjunct Asst Professor
36 Research Asst Professor
38 Instructional Assistant Professor
39 Visiting Research Asst Prof
40 Instructor
41 Instructor in Clinical
42 Adj Instructor in Clinical
43 Visiting Instructor
45 Adjunct Instructor
46 Research Instructor
49 Instructor Contingency Appt
50 Senior Research Associate
51 Senior Clinical Associate
52 Adj Senior Clinical Associate
54 Research Scientist/Analyst/Engineer
55 Adjunct Senior Research Assoc
59 Sr Research Assoc & Lecturer
60 Research Associate
61 Clinical Associate
62 Adj Clinical Associate
63 Administrative Associate
64 Senior Research Scientist/Analyst/Engineer
65 Adjunct Research Associate
70 Senior Lecturer
71 Lecturer
73 Visiting Lecturer
74 Principal Research Scientist/Analyst/Engineer
79 Intern
80 Non-specific Courtesy Appt
83 Visiting Scientist
84 Distinguished Fellow
89 Guest Design/Lighting
90 Research Fellow
91 Clinical Fellow

faculty_rank_status code and descriptions

Value Description
A Acting Chair
C Chair
D Director
E Emeritus/a
H Honorary
I Interim Chair
ID Interim Director
V Vice Chair

tenure_status code and descriptions

Value Description
NT Non-Tenured
NT DMSC Non-Tenured, DMS Clinical Faculty
NT DMSO Non-Tenured, DMS Other Faculty
NT DMSR Non-Tenured, DMS Research Faculty
T Tenured
TT Tenure Track

emeritus_data descriptions

Field Type Sample Data Description Known Issues
salutation string Ms
year_of_appointment string 1977
emeritus_title string Professor of Music, Emerita
email_after_termination string YES
status_grant_year string 2019
status_grant_month string August
emeritus_organization object see structure definition above

Sample Request

https://api.dartmouth.edu/api/employee/d59951y

Sample Return

{
    "birth_date": "1969-01-19",
    "cache_date": "2020-07-16T19:20:17Z",
    "emeritus_data": null,
    "faculty_data": null,
    "schedule_data": {
        "work_schedule": {
            "start_time": "06:00",
            "end_time": "14:30"
        },
        "scheduled_daysoff": [
            "SUN",
            "SAT"
        ]
    },
    "home_department": "Human Resources Operations",
    "i9_date": null,
    "i9_status": "Yes",
    "is_benefits_eligible": true,
    "is_med_enrolled": true,
    "jobs": [
        {
            "assignment_number": "32510-8",
            "is_home_department": true,
            "job_base_status": "Regular",
            "job_current_status": "Active",
            "job_end_date": null,
            "job_group": "Staff",
            "job_organization": {
                "academic_division": "Human Resources",
                "department": "Human Resources Operations",
                "division": "Finance and Admin",
                "id": "5bbe5ff0129f9a5a96149102",
                "organization": "Human Resources Operations",
                "organization_namespace": "human_resources",
                "sub_division_or_school": "Human Resources",
                "subunit": "Human Resources Operations",
                "unit": "Human Resources Operations"
            },
            "job_start_date": "2019-08-02T04:00:00Z",
            "job_type": "Exempt Staff",
            "location": {
                "description": "7 Lebanon St, Room 251",
                "building_id": "0601",
                "space_id": "251"
            },
            "original_job_start_date": "2016-01-01T05:00:00Z",
            "payroll_type": "Monthly",
            "position_title": "Executive Director, HR Services",
            "supervisor_netid": "f0029x1",
            "maintenance_crew": {
                "crew_code": "JD",
                "crew_shift": "1B",
                "shop_lead": true
            }
        }
    ],
    "netid": "d33961y",
    "person_type": [
        "Employee"
    ],
    "primary_payroll": "Monthly"
}

Sample Return Faculty Data

    "faculty_data": [
        {
            "faculty_rank": {
                "status": null,
                "code": "10",
                "rank_date": "1998-07-01T04:00:00Z",
                "description": "Professor"
            },
            "organization": {
                "long_name": "Surgery",
                "name": "Surgery",
                "department": "Surgery",
                "sub_division": "Medical School",
                "id": "5bbe5ff0129f9a5a96149107",
                "academic_division": "Medical School",
                "subunit": "Surgery",
                "school": "Medical School",
                "sub_division_or_school": "Medical School",
                "division": "Provosts Office",
                "unit": "Surgery",
                "org_type": "Department",
                "org_parent_id": "5bbe5ff0129f9a5a961492e7",
                "gl_org_code": "466"

            },
            "tenure_status": {
                "code": "NT DMSC",
                "tenure_date": null,
                "description": null
            },
            "as_of_indicator": "Today"
        },
        {
            "faculty_rank": {
                "status": null,
                "code": "10",
                "rank_date": "1998-07-01T04:00:00Z",
                "description": "Professor"
            },
            "organization": {
                "long_name": "Anesthesiology",
                "name": "Anesthesiology",
                "department": "Anesthesiology",
                "sub_division": "Medical School",
                "id": "5bbe5ff0129f9a5a961490d2",
                "academic_division": "Medical School",
                "subunit": "Anesthesiology",
                "school": "Medical School",
                "sub_division_or_school": "Medical School",
                "division": "Provosts Office",
                "unit": "Anesthesiology",
                "org_type": "Department"
            },
            "tenure_status": {
                "code": "NT DMSC",
                "tenure_date": null,
                "description": null,
                "asst_prof_start_term": null
            },
            "as_of_indicator": "Today"
        }
    ],

Sample Return Emeritus Data

    "emeritus_data": {
        "salutation": "Doctor",
        "year_of_appointment": "2003",
        "emeritus_title": "Professor of Medicine, Community and Family Medicine, and the Dartmouth Institute, Emeritus",
        "email_after_termination": "YES",
        "status_grant_month": "December",
        "status_grant_year": "2018",
        "emeritus_organization": {
            "organization_namespace": "human_resources",
            "id": "5bbe5ff0129f9a5a9614916b",
            "organization": "Medicine",
            "division": "Provosts Office",
            "sub_division_or_school": "Medical School",
            "academic_division": "Medical School",
            "department": "Medicine",
            "subunit": "Medicine",
            "unit": "Medicine"
        }
    }