Dartmouth API Developer Portal

Academic Enrollments API - PATCH

Supports update of course_assessment status in enrollments.

Required Scopes

Scope Description
api:academic:enrollments:read This scope is required in order to read enrollments. Granting of this scope is via the Undergraduate Registrars Office
api:academic:enrollments:read.sensitive This scope is required in order to read sensitive enrollment attributes (e.g. final_grade). Granting of this scope is via the Undergraduate Registrars Office
api:academic:enrollments:write This scope is required in order to write enrollment attributes (i.e. course_assessment). Granting of this scope is via the Undergraduate Registrars Office
urn:dartmouth:people:private This optional scope is required in order to get enrollments for FERPA-protected students. Granting of this scope is via the Undergraduate Registrars Office

Request

PATCH /api/academic/enrollments/{id}

Required Headers

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

Payload

PATCH payload must be included in the request body and must include all course_assessment attributes. Here is an example payload: 

{
    "course_assessment": {
        "submit_date": "2020-03-05T17:53:46Z",
        "opt_out_date": null
    }
}

Notes on usage

The enrollments API checks the validity of the payload and the presence of required scopes. 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 payload contains a complete course_assessment object: it must contain both submit_date and opt_out_date; but only one of these can contain a value, the other must be null. To clear course assessment, set both to null. (This will result in a course_assessment value of null for the associated enrollment.

Returns

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

Sample Request

https://api.dartmouth.edu/api/academic/enrollments/AAAS.010.01-202001-U-10188-f002qt1-student

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 and message are null:

{
    "status": "accepted",
    "path": null,
    "message": null,
    "id": "630cf2e78b1c6c251cfbc125"
}

Sample Successfull Task

For successfully completed tasks, path is set to the url of the enrollment that was updated and message provides details of the operation completed.

{
    "status": "complete",
    "path": "https://api-dev.dartmouth.edu/api/academic/enrollments/AAAS.010.01-202001-U-10188-f002qt1-student",
    "message": "Enrollment updated successfully.",
    "id": "630cf2e78b1c6c251cfbc125"
}

Sample Failed Task

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

{
    "status": "error",
    "path": "https://api-dev.dartmouth.edu/api/academic/enrollments/AAAS.010.01-202001-U-10188-f002qt1-student",
    "message": "['Payload is invalid, contains values for both submit_date and opt_out_date.']",
    "id": "630cf3b161b5fada66eb9358"
}