Dartmouth API Developer Portal

People API

Returns high level directory type information like name and email address about identities at Dartmouth College

Rating

Attribute Value
Highly Available Yes
Cache Refresh Interval Every 5 minutes
Filtering Yes

Required Scopes

Scope Description
"urn:dartmouth:people:private" This optional scope is required in order to view FERPA protected identities. Granting of this scope is via the Undergraduate Registrars Office
"urn:dartmouth:people:read.sensitive" This optional scope is required in order to view sensitive attributes. Granting of this scope is approved by the data stewards of the underlying data sources and require several approvals
"urn:dartmouth:people:read.highlysensitive" This optional scope is required in order to view highly sensitive attributes. Granting of this scope is approved by the data stewards of the underlying data sources and require several approvals

Request

GET /api/people/{netid}

Required Headers

Authorization: Bearer {jwt}

Notes on usage

The people API returns data from a source system based on the identity's primary data source or affinity. For employees that is the HRS system, Students from the SIS and identities with no affiliation (sponsored accounts, service accounts etc.) from IDM. Currently Alumni affiliated records are also coming from IDM. Future enhancements will return data directly from the Advancement system.

Telephone Numbers

Telephone numbers from the multiple source systems are merged together in this API. Each telephone number in the telphone_numbers collection has an attribute called data_source which identifies the source system for the phone number. Telephone types associated with each number can be looked up with the /api/telephone_types API. Telephone types from sis are straight mappings of Banner telephone type codes. For hrs sourced telephone numbers the telephone_type_id is the HRMS telephone type prepended with the string HRS (to guarantee uniqueness). The idm source telephone number has no source type associated with it, and is assigned a fictional telephone type of IDMCP (for IDM Campus Phone). Additionally and attribue data_source will tell you specifically the data source originating the telephone number, the values for this attribute currently can be idm,hrs,sis,adv.

Addresses

Addresses from the multiple source systems are merged together in this API. Each address in the addresses collection has an attribute called data_source which identifies the source system for the address. Address types associated with each adress can be looked up with the /api/address_types API. Address types from sis are straight mappings of Banner telephone type codes. For hrs sourced telephone numbers the address_type_id is the HRMS telephone type prepended with the string HR (to guarantee uniqueness). Additionally the attribue data_source will tell you specifically the data source originating the telephone number, the values for this attribute currently can be hrs,sis.

Citizenship Logic

Detailed description on how citizenship is derived for Students

Ipaas provides 4 citizenship fields: citizenship_type_id, is_usa_citizen, citizenship_country_id , and citizenship_country2_id

citizenship_type_id

is_usa_citizen

Tuck:

All other schools:

citizenship_country_id

Tuck:

citizenship_country2_id

Tuck:

First choice:

Gender and chosen pronoun (Only applies to people with primary affiliation of student)

chosen_pronoun (below are the possible scenarios with examples):

chosen_gender

gender_id

legal_sex_id (below are possible values)

"F"
"M"

Returns

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

Sample Request

https://api.dartmouth.edu/api/people/f003x0n

Sample Return

With urn:dartmouth:people:read.sensitive scope:

{
    "account_status": "Active",
    "addresses": [
        {
            "address_id": "5ce6fe8f129f9a1e4e145308",
            "address_type_id": "K1",
            "city": "South Barrington",
            "country_id": "US",
            "data_source": "sis",
            "from_date": "2015-05-22T04:00:00Z",
            "postal_code": "60010-5311",
            "sis_id": "5ce6fe8f129f9a1e4e145308",
            "state_id": "IL",
            "street_line_1": "36 Lakeside Drive",
            "street_line_2": null,
            "street_line_3": null,
            "to_date": null
        },
        {
            "address_id": "5ce6fe8f129f9a1e4e145309",
            "address_type_id": "LO",
            "city": "Hanover",
            "country_id": null,
            "data_source": "sis",
            "from_date": "2019-01-02T05:00:00Z",
            "postal_code": "03755",
            "sis_id": "5ce6fe8f129f9a1e4e145309",
            "state_id": "NH",
            "street_line_1": "Morton 110",
            "street_line_2": null,
            "street_line_3": null,
            "to_date": "2019-03-14T04:00:00Z"
        }
    ],
    "affiliations": [
        {
            "name": "Staff"
        }
    ],
    "barcode": "23311001030428",
    "cache_date": "2018-02-21T23:06:45Z",
    "campus_address": null,
    "chosen_gender": {
        "id": "W"
    },
    "chosen_pronoun": {
        "id": "SHE",
        "other_value": null
    },
    "citizenship_country2_id": null,
    "citizenship_country_id": null,
    "citizenship_type_id": null,
    "created_date": "2018-02-21T23:06:45Z",
    "dartcard_id": "100180108",
    "dartmouth_affiliation": "DART",
    "email": "Dougie.A.Houser@Dartmouth.EDU",
    "expires_date": null,
    "first_name": "Dougie",
    "gender_id": false,
    "has_name_recording": false,
    "is_18_years_of_age": true,
    "is_confidential": false,
    "is_identity_claimed": true,
    "is_phi_user": true,
    "is_usa_citizen": true,
    "is_veteran": null,
    "last_name": "Houser",
    "legal_first_name": "Dougie",
    "legal_last_name": "Houser",
    "legal_middle_name": "A",
    "legal_name": "Dougie A Houser",
    "legal_prefix": null,
    "legal_suffix": null,
    "middle_name": "A",
    "name": "Dougie A Houser",
    "netid": "f003x0n",
    "nickname": "Doc",
    "personal_email": null,
    "prefix": null,
    "primary_affiliation": "Staff",
    "prox_id": 117363,
    "religion_id": null,
    "sis_person_id": "2544322",
    "spouse": {
        "name": "Jane J. Houser"
    },
    "suffix": null,
    "telephone_numbers": [
        {
            "area_code": null,
            "country_id": null,
            "data_source": "idm",
            "extension": null,
            "from_date": "2018-09-12T13:16:21Z",
            "is_international": false,
            "number": "603-646-3023",
            "telephone_type_id": "BU",
            "to_date": null
        }
    ]
}

Dartmouth Affiliation Values

Code Description
ALUMNI Alumni account
DART Student, Faculty, Staff, or ExEmployee
DEPT Departmental account
E-FAC Emeritus faculty (or staff); keep account active regardless of HR status
ORG Student organization
P-ADM "private" accounts for senior administration
SERVICE Service account for applications that need to authenticate, send mail, etc.
SPON Sponsored account
SPONLIM Limited-access sponsored account (guest account), or social media account
TRUSTEE Member of the board of Trustees (they aren't employees, so aren't fed from HR)

These values should only occur on Disabled accounts, and should be considered obsolete:

Code Description
DHMC DHMC employee with a Dartmouth BlitzMail account (legacy, from before DHMC ran its own mail system)
GROUP DND group for file permissions in AppleShare file servers
SEMINAR short-term sponsored accounts for Tuck seminars; regular sponsored or guest accounts are now used instead
S-FAC "special faculty" who are paid for only 1 term but should have a valid account year-round. No longer needed due to improvements in HR reporting of "active" status for such people

With no scope

When no scope is specified, the following attributes are omitted from the return payload: legal_name,legal_first_name, legal_last_name, legal_middle_name, legal_prefix, legal_suffix, nickname, spouse, telephone_numbers, addresses, personal_email, primary_affiliation, dartmouth_affiliation, affiliations, gender_id, account_status, is_identity_claimed, is_confidential, is_phi_user, barcode, chosen_gender, chosen_pronoun, citizenship_type_id, citizenship_country_id, citizenship_country2_id, dartcard_id, is_usa_citizen, religion_id, sis_person_id, created_date, and expires_date removed):

{
    "netid": "f003x0n",
    "name": "Dougie A Houser",
    "first_name": "Dougie",
    "last_name": "Houser",
    "middle_name": "A",
    "email": "Dougie.A.Houser@Dartmouth.EDU",
    "prefix": null,
    "suffix": null,
    "has_name_recording": false,
    "cache_date": "2018-02-21T23:06:45Z",
    "campus_address": null
}

With urn:dartmouth:people:private scope

When the urn:dartmouth:people:private scope is specified the return payload is same as with no scope specified but now the is_confidential attribute is returned.

{
    "netid": "f003x0n",
    "name": "Dougie A Houser",
    "first_name": "Dougie",
    "last_name": "Houser",
    "middle_name": "A",
    "email": "Dougie.A.Houser@Dartmouth.EDU",
    "prefix": null,
    "suffix": null,
    "has_name_recording": false,
    "cache_date": "2018-02-21T23:06:45Z",
    "is_confidential": false,
    "campus_address": null
}

With urn:dartmouth:people:read.highlysensitive scope:

When the urn:dartmouth:people:read.highlysensitive scope is specified the return payload includes birth_date, legal_sex_id, is_veteran, and ethnicity. The example below shows the result when urn:dartmouth:people:read.highlysensitive scope alone; if combined with other scopes (e.g. urn:dartmouth:people:read.sensitive) the payload would also include the attributes associated with that scope.

{
    "netid": "f003x0n",
    "name": "Dougie A Houser",
    "first_name": "Dougie",
    "last_name": "Houser",
    "middle_name": "A",
    "email": "Dougie.A.Houser@Dartmouth.EDU",
    "prefix": null,
    "suffix": null,
    "has_name_recording": false,
    "cache_date": "2018-02-21T23:06:45Z",
    "campus_address": null,
    "birth_date": "2000-12-31",
    "legal_sex_id": null,
    "is_veteran": null,
    "ethnicity": "Other"
}

Filtering

The Dartmouth People API contains information on over 100,000 people. Most use cases only need to work with subsets of the total population. Instead of supplying a netid parameter to request information for a single person, optional query parameters may be included in a request to the People API which will be used to return a subset of People whose attributes match the specified filters.

See the introductory section on Filtering and Paging for more details

Resource Changes

The DartAPI service also supports subscribing to special notification subscription channels that allow you to find all changes for different resources such as People, Employees or Students. Subscribing to that notification will allow you to keep a shadow data set in synchronization with a trickle of changes rather than having to fully reload. Currently the service only supports polling for change notifications. A future enhancement may support webhook notifications (push changes rather than pull).

Field Definitions

Field Type Sample Data Description Required Scope
account_status string Active IDM Account Status which can be Active or Disabled urn:dartmouth:people:read.sensitive
addresses Array Array of address objects urn:dartmouth:people:read.sensitive
affiliations Array Array of affiliation objects, a person can be in multiple affiliations, but only one affiliation is designated "Primary" urn:dartmouth:people:read.sensitive
barcode string 23311001247612 urn:dartmouth:people:read.sensitive
birth_date string 2000-12-31 Birth Date in YYYY-MM-DD format for students only, employees do not supply birth_date urn:dartmouth:people:read.highlysensitive
cache_date string 2016-01-01T05:00:00Z the last update of the cache for this record in iso8601 format urn:dartmouth:people:read.sensitive
campus_address string 6042 the campus address aka HB or Hinman Box for people on campus urn:dartmouth:people:read.sensitive
chosen_gender object See notes on usage section for more details urn:dartmouth:people:read.sensitive
chosen_pronoun: object See notes on usage section for more details urn:dartmouth:people:read.sensitive
citizenship_country2_id string see detailed description below on how citizenship is sourced from different systems urn:dartmouth:people:read.sensitive
citizenship_country_id string see detailed description below on how citizenship is sourced from different systems urn:dartmouth:people:read.sensitive
citizenship_type_id string see detailed description below on how citizenship is sourced from different systems urn:dartmouth:people:read.sensitive
created_date string urn:dartmouth:people:read.sensitive
dartcard_id string currently sourced from Lenel. This ID is fed to the CSGOLD dining system as the PIK number urn:dartmouth:people:read.sensitive
dartmouth_affiliation string DART This code identifies the affiliation associated with the account, for example Emeritus or Sponsored accounts. See table below for all values and descriptions urn:dartmouth:people:read.sensitive
email string Joe.A.User@Dartmouth.EDU IDM sourced email address (need definition on how this is derived)
ethnicity string Filipino Ethnicity for students only urn:dartmouth:people:read.highlysensitive
expires_date string 2019-01-24T05:00:00Z IDM sourced expiration of the account urn:dartmouth:people:read.sensitive
first_name string
gender_id string urn:dartmouth:people:read.sensitive
has_name_recording boolean true true for identities that have recorded their names using say-my-name.dartmouth.edu urn:dartmouth:people:read.sensitive
is_18_years_of_age boolean true true for students if 18 years or older, students only, employees do not supply birth date information urn:dartmouth:people:read.sensitive
is_confidential boolean true true for students that have requested confidentiality flagging urn:dartmouth:people:read.sensitive
is_identity_claimed boolean true true for identities that have set their password; may be false for non-person or older (Active) identities urn:dartmouth:people:read.sensitive
is_phi_user boolean false true for identities that handle PHI/HIPAA information. For employees this is driven from their home assignment organization urn:dartmouth:people:read.sensitive
is_usa_citizen boolean true urn:dartmouth:people:read.sensitive
is_veteran boolean true true for students who are veterans, students only urn:dartmouth:people:read.highlysensitive
last_name string
legal_first_name string urn:dartmouth:people:read.sensitive
legal_last_name string urn:dartmouth:people:read.sensitive
legal_middle_name string urn:dartmouth:people:read.sensitive
legal_name string urn:dartmouth:people:read.sensitive
legal_prefix string urn:dartmouth:people:read.sensitive
legal_sex_id string urn:dartmouth:people:read.highlysensitive
legal_suffix string urn:dartmouth:people:read.sensitive
middle_name string
name string
netid string
nickname string
personal_email string for students the email is derived from the the latest active ALTE from sis, for other sources the email comes from IDMs derivation of personal email urn:dartmouth:people:read.sensitive
prefix string
primary_affiliation string Dartmouth follows documented standard xxx.xxxx for determining primary affiliation. The possible values are Staff,None,Alum,Student,Affiliate,ExEmployee,Faculty,Member,Social urn:dartmouth:people:read.sensitive
prox_id integer 117363 The proximity id assigned to this person's id badge. Sourced from Lenel system urn:dartmouth:people:read.sensitive
religion_id string urn:dartmouth:people:read.sensitive
sis_person_id string urn:dartmouth:people:read.sensitive
spouse string urn:dartmouth:people:read.sensitive
suffix string
telephone_numbers Array Array of telephone objects urn:dartmouth:people:read.sensitive