Dartmouth API Developer Portal

Students API - PATCH

Supports partial updates for students at Dartmouth College.

Required Scopes

Scope	Description
"urn:dartmouth:students:write.sensitive"	This scope is required in order to write sensitive attributes. Granting of this scope is approved by the Undergraduate Registrars Office
"urn:dartmouth:students: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 Undergraduate Registrars Office
"urn:dartmouth:people:private"	This optional scope is required in order to update FERPA protected students. Granting of this scope is via the Undergraduate Registrars Office

Request

PATCH /api/students/{netid}

Required Headers

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

Payload

PATCH payload must be included in the request body. PATCH is currently limited to dplans. Here is an example payload:

{
    "dplans": [
        {
            "dplan_description": "Resident",
            "dplan_source_id": "PHL",
            "dplan_id": "R",
            "dplan_source_description": "Registrar Action",
            "term_code": "202301"
        },
                {
            "dplan_description": "Resident",
            "dplan_source_id": "PHL",
            "dplan_id": "R",
            "dplan_source_description": "Registrar Action",
            "term_code": "202303"
        }
    ]
}

Field	Type	Description
dplan_description	string	Not required, ignored
dplan_source_id	string	Must be a valid ID
dplan_id	string	Must be a valid ID
dplan_source_description	string	Not required, ignored
term_code	string	Must be a valid SIS term code

Notes on usage

PATCH adds/replaces dplans by term. If you specify a single dplan/term, only the dplan associated with that term is added/updated; all other existing dplan records remain unchanged.

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

Sample Request

https://api.dartmouth.edu/api/students/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, path is null:

{
    "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 result.

{
    "resource": "students",
    "action": "PATCH",
    "resource_id": "f0027k4",
    "payload": {
        "dplans": [
            {
                "dplan_description": "Resident",
                "dplan_source_id": "PHL",
                "dplan_id": "R",
                "dplan_source_description": "Registrar Action",
                "term_code": "202501"
            },
            {
                "dplan_description": "Resident",
                "dplan_source_id": "PHL",
                "dplan_id": "R",
                "dplan_source_description": "Registrar Action",
                "term_code": "202503"
            }
        ]
    },
    "requester": {
        "sub": "f003ghc",
        "name": "Integration Test User",
        "email": "Integration.Test.User@dartmouth.edu",
        "scope": "urn:dartmouth:students:write.sensitive,urn:dartmouth:tasks:students:write,urn:dartmouth:students:read.sensitive",
        "exp": "1676913785",
        "iat": "1676902985"
    },
    "status": "complete",
    "request_date": "2023-02-20T14:34:08Z",
    "completed_date": "2023-02-20T14:34:11Z",
    "path": null,
    "worker_data": null,
    "message": "success",
    "id": "63f384e0edba4dc38df70324"
}

Sample Failed Task

For failed tasks, path is set to null and status indicates "error"

{
    "resource": "students",
    "action": "PATCH",
    "resource_id": "f0027k4",
    "payload": {
        "dplans": [
            {
                "dplan_description": "Resident",
                "dplan_id": "R",
                "dplan_source_description": "Registrar Action",
                "term_code": "202501"
            },
            {
                "dplan_description": "Resident",
                "dplan_source_id": "PHL",
                "dplan_source_description": "Registrar Action",
                "term_code": "202503"
            }
        ]
    },
    "requester": {
        "sub": "f003ghc",
        "name": "Integration Test User",
        "email": "Integration.Test.User@dartmouth.edu",
        "scope": "urn:dartmouth:students:write.sensitive,urn:dartmouth:tasks:students:write,urn:dartmouth:students:read.sensitive",
        "exp": "1676913785",
        "iat": "1676902985"
    },
    "status": "error",
    "request_date": "2023-02-20T14:38:17Z",
    "completed_date": "2023-02-20T14:38:28Z",
    "path": null,
    "worker_data": null,
    "message": "'dplan_source_id'",
    "id": "63f385d98643308c4ab37f19"
}