Dartmouth API Developer Portal

People API - PATCH

Supports partial updates for identities at Dartmouth College. (Currently limited to students.)

Required Scopes

Scope	Description
"urn:dartmouth:people:write.sensitive"	This scope is required in order to write sensitive attributes. Granting of this scope is approved by the Chief Technology Officer of ITC
"urn:dartmouth:people:read.sensitive"	This scope is required in order to release sensitive attributes; both read and write scopes are required. Granting of this scope is approved by the Chief Technology Officer of ITC
"urn:dartmouth:people:private"	This optional scope is required in order to update FERPA protected identities. Granting of this scope is via the Undergraduate Registrars Office

Request

PATCH /api/people/{netid}

Required Headers

Authorization: Bearer {jwt}
Content-Type: application/json

Payload

PATCH payload must be included in the request body. Here is an example of a payload with all available PATCH attributes:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "middle_name": null,
  "chosen_gender": {"id":"W"},
  "chosen_pronoun": {"id":"SHE","other_value": null},
  "religion_id": "JE",
  "personal_email": null,
  "addresses": [
    {
        "address_type_id": "K1",
        "street_line_1": "36 River Rd",
        "street_line_2": null,
        "street_line_3": null,
        "city": "North Bizzington",
        "state_id": "IL",
        "postal_code": "60010-5131",
        "country_id": "US"
    },
    {
        "address_type_id": "LO",
        "street_line_1": "Morton 110",
        "street_line_2": null,
        "street_line_3": null,
        "city": "Hanover",
        "state_id": "NH",
        "postal_code": "03755",
        "country_id": null
    }
  ],

}

Attributes can be PATCHed individually, for example:

{
  "personal_email": "someone@somewhere.org"
}

However, when PATCHing name components both first_name and last_name must be included in the payload with non-null values (middle_name is not required):

{
  "first_name": "Jane",
  "last_name": "Doe"
}

To revert to legal name, include all 3 name components in the payload with null values:

{
  "first_name": null,
  "last_name": null,
  "middle_name": null
}

Field	Type	Description
first_name	string	Must also include last_name, cannot be null
last_name	string	Must also include first_name, cannot be null
middle_name	string
chosen_gender.id	string	Must be a valid gender id (from /genders API) or null
chosen_pronoun.id	string	Must be a valid pronoun id (from /personal_pronouns API) or null
chosen_pronoun.other_value	string	Only recognized with chosen_pronoun.id = "O"
religion_id	string	Must be a valid religion id (from /religions API) or null
personal_email	string
addresses	array	Can be an empty array, cannot be null
addresses[i].address_type_id	string	Must be a valid address_type id (from /address_types API); cannot be null
addresses[i].street_line_1	string
addresses[i].street_line_2	string
addresses[i].street_line_3	string
addresses[i].city	string
addresses[i].state_id	string	Must be a valid state id (from /states API) or null
addresses[i].postal_code	string
addresses[i].country_id	string	Must be a valid country id (from /countries API) or null

Notes on usage

The people API checks the validity of the payload, the presence of required scopes, and confirms that the requested people record exists. It then submits the request to a task queue and returns the url of the task in the location header. The consumer must poll the task until completion.

The addresses portion of the payload represents the complete set of addresses for the specified netid. PATCH will create, update, or delete addresses so that current addresses for the associated person match the payload exactly.

Returns

Status Code	Description
202	The URI parameter {netid} passed in is a valid identity, request payload is valid, and the required scopes are in place
404	The URI parameter {netid} passed in is NOT a valid identity
400	Invalid attributes in payload

Sample Request

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

Sample Return

{
    "status": "accepted"
}

Sample Response Header

Location: /api/tasks/5cddb466b68a450c3b102bfd

Task Monitoring

After a PATCH request has been accepted, the consumer must poll the task until completion using the following request:

GET /api/tasks/{id}

Here is an example using the task id from above:

https://api.dartmouth.edu/api/tasks/5cddb466b68a450c3b102bfd

Sample Incomplete Task

For incomplete tasks, status indicates "accepted":

{
    "status": "accepted",
}

Sample Successfull Task

For successfully completed tasks, path is set to the url of the resource that was updated and status provides details of the operation(s) completed.

{
    "action": "PATCH",
    "completed_date": "2023-02-20T14:14:53Z",
    "id": "63f3805aedba4dc38df7031d",
    "path": "https://api-dev.dartmouth.edu/api/people/f0027k4",
    "payload": {
        "addresses": [
            {
                "address_type_id": "PR",
                "city": "Norwich",
                "country_id": null,
                "postal_code": "05055",
                "state_id": "VT",
                "street_line_1": "40 Starlóke Lane",
                "street_line_2": null,
                "street_line_3": null
            }
        ],
        "chosen_gender": {
            "id": "W"
        },
        "chosen_pronoun": {
            "id": "SHE",
            "other_value": null
        },
        "first_name": "Imélda",
        "last_name": "Zestoz",
        "middle_name": "M",
        "name": "this is ignored",
        "personal_email": "invalid@nowhere.edu",
        "religion_id": "JE"
    },
    "request_date": "2023-02-20T14:14:50Z",
    "requester": {
        "email": "Integration.Test.User@dartmouth.edu",
        "exp": "1676913267",
        "iat": "1676902467",
        "name": "Integration Test User",
        "scope": "urn:dartmouth:people:write.sensitive,urn:dartmouth:people:read.sensitive",
        "sub": "f003ghc"
    },
    "resource": "people",
    "resource_id": "f0027k4",
    "status": "SUCCESS: spbpers updated successfully, spraddr updated successfully for f0027k4",
    "worker_data": null
}

Sample Failed Task

For failed tasks, path is set to the url of the resource that was supposed to be updated and status provides details of the failure.

{
    "action": "PATCH",
    "completed_date": "2023-02-20T14:19:09Z",
    "id": "63f3815c8643308c4ab37f15",
    "path": "https://api-dev.dartmouth.edu/api/people/f0027k4",
    "payload": {
        "addresses": [
            {
                "address_type_id": "PR",
                "city": "Norwich",
                "country_id": null,
                "postal_code": "05055",
                "state_id": "VT",
                "street_line_1": "40 Starlóke Lane",
                "street_line_2": null,
                "street_line_3": null
            }
        ],
        "chosen_gender": {
            "id": "W"
        },
        "chosen_pronoun": {
            "id": "SHE",
            "other_value": null
        },
        "first_name": "Imélda",
        "last_name": "Zestoz",
        "middle_name": "M",
        "name": "this is ignored",
        "personal_email": "invalid@nowhere.edu",
        "religion_id": "XX"
    },
    "request_date": "2023-02-20T14:19:08Z",
    "requester": {
        "email": "Integration.Test.User@dartmouth.edu",
        "exp": "1676913267",
        "iat": "1676902467",
        "name": "Integration Test User",
        "scope": "urn:dartmouth:people:write.sensitive,urn:dartmouth:people:read.sensitive",
        "sub": "f003ghc"
    },
    "resource": "people",
    "resource_id": "f0027k4",
    "status": "FAILURE: spbpers update failed: ('(cx_Oracle.IntegrityError) ORA-02291: integrity constraint (SATURN.FK1_SPBPERS_INV_STVRELG_CODE) violated - parent key not found',) for f0027k4",
    "worker_data": null
}