Dartmouth API Developer Portal

People API

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

Rating

Required Scopes

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

• Equal to spbpers_citz_code
• Use api/citizenship_types to get description associated with citizenship_type_id

is_usa_citizen

Tuck:

• True if spbpers_citz_code in (U,P)
• False if spbpers_citz_code in (N,D)
• Null if spbpers_citz_code is any other value (including null)

All other schools:

• Null if spbpers_citz_code is null
• True if spbpers_citz_code = U
• False if spbpers_citz_code is any other value

citizenship_country_id

Tuck:

• US if is_usa_citizen is True (per logic above), otherwise: First choice:
• Stvnatn_code associated with Stvnatn_nation that matches saracmt_comment_text where saracmt_orig_code=BOC If first choice is not available:
• Stvnatn_code associated with Stvnatn_nation that matches first comma-delimited value of saracmt_comment_text where saracmt_orig_code=BDC All other schools:
• US if is_usa_citizen is True (per logic above), otherwise gobintl_natn_code_legal

citizenship_country2_id

Tuck:

First choice:

• Stvnatn_code associated with Stvnatn_nation that matches second comma-delimited value of saracmt_comment_text where saracmt_orig_code=BDC If first choice is not available:
• Stvnatn_code associated with Stvnatn_nation that matches full value of saracmt_comment_text where saracmt_orig_code=BDC All other schools:
• Null

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

chosen_pronoun (below are the possible scenarios with examples):

• If person has "other_value" of "SHE/THEM"

  "chosen_pronoun": {"id": "other", "other_value": "SHE/THEM"}
  

• If person previously had "other_value" of "SHE/THEM" and later chose "TH". Then that person's chosen_pronoun "id" will be "TH" and "other_value" will still remain "SHE/THEM". However the "other_value" is meaningless at this point. Note: "other_value" is only meaningful when "id" = "other"

  "chosen_pronoun": {"id": "TH", "other_value": "SHE/THEM"}
  

• If person chose "SHE"

  "chosen_pronoun": {"id": "SHE", "other_value": null}
  

chosen_gender

• Go to the genders end point to get a list of valid values (/api/genders)

• An example below:

  "chosen_gender": {"id": "W"}
  

gender_id

• Defaults to "MN" for people with legal_sex_id of "M"
• Default to "W" for people with legal_sex_id of "F"
• chosen_gender["id"] and gender_id are the same

legal_sex_id (below are possible values)

"F"
"M"

Returns

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": null,
    "is_18_years_of_age": true,
    "is_confidential": false,
    "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

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

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_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,
    "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,
    "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,
    "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