Dartmouth API Developer Portal

Academic Attendance API - POST

Supports addition of a new student petition.

Required Scopes

Scope	Description
api:academic:petitions:write	This scope is required in order to write petition attributes (i.e. attendance). Granting of this scope is via the Undergraduate Registrars Office

Request

POST /api/academic/petitions

Required Headers

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

Payload

POST payload must be included in the request body and must include all required petition attributes. Here is an example payload:

{
    "petition": {
        "netid": "f006kdf",
        "petition_code": "Q41",
        "origin_code": "UREG",       
        "school": "UG", 
        "decision": "IDP 095", 
        "grade_term": "24F",   
        "user_netid": "f006s0b"   
    }
}

Notes on usage

The academic/petitions API checks the presence of required scopes. It then submits the request to a task queue, which returns the url of the task in the location header. The consumer must poll the task until completion. The task checks validity of the payload and then performs the task. If successful, the URL of the created or updated attendance is included in the task 'path' attribute.

The payload contains all necessary fields required to insert a partition in the SHREVNT table.

Returns

Status Code	Description
202	The required scopes are in place and the task has been added to the task queue
403	The required scopes are in not in place

Sample Request

https://api.dartmouth.edu/api/academic/petitions

Sample Return

{
    "status": "accepted"
}

Sample Response Header

Location: /api/tasks/5cddb466b68a450c3b102bfd

Task Monitoring

After a POST 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 is 'accepted'; path and message are null:

673e4c82185254cacb8d2967

Sample Successfull Task

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

{
    "resource": "academic.petitions",
    "action": "POST",
    "resource_id": null,
    "payload": {
        "netid": "f006s0b",
        "petition_code": "Q41",
        "origin_code": "UREG",
        "school": "UG",
        "decision": "2023-2024",
        "grade_term": "24W",
        "user_netid": "F006S0B"
    },
    "requester": {
        "sub": "f0057pn",
        "name": "DPLAN API",
        "email": "DPLAN.API@dartmouth.edu",
        "scope": "api:academic:petitions:read,urn:dartmouth:students:read.sensitive,urn:dartmouth:students:read.sensitive,urn:dartmouth:people:private,api:academic:petitions:write",
        "exp": "1732141853",
        "iat": "1732131053"
    },
    "status": "complete",
    "request_date": "2024-11-20T20:54:26Z",
    "completed_date": "2024-11-20T20:54:27.328833",
    "path": "/academic/petitions/673e4c83255f18cce280f5d7",
    "worker_data": {},
    "id": "673e4c82185254cacb8d2967",
    "message": "Petition created successfully. mongo id 673e4c83255f18cce280f5d7 "
}

Sample Failed Task

For failed tasks, path is set to the called url and message provides details of the failure.

{
    "resource": "academic.petitions",
    "action": "POST",
    "resource_id": null,
    "payload": {
        "netid": "f006s0b",
        "petition_code": "Q41",
        "origin_code": "UREG",
        "school": "UG",
        "decision": "2023-2024",
        "grade_term": "24W",
        "user_netid": "F006S0B"
    },
    "requester": {
        "sub": "f0057pn",
        "name": "DPLAN API",
        "email": "DPLAN.API@dartmouth.edu",
        "scope": "api:academic:petitions:read,urn:dartmouth:students:read.sensitive,urn:dartmouth:students:read.sensitive,urn:dartmouth:people:private,api:academic:petitions:write",
        "exp": "1732141853",
        "iat": "1732131053"
    },
    "status": "complete",
    "request_date": "2024-11-20T20:54:26Z",
    "completed_date": "2024-11-20T20:54:27.328833",
    "path": "/academic/petitions/673e4c82185254cacb8d2967",
    "worker_data": {},
    "id": "673e4c82185254cacb8d2967",
    "message": "Petition did not update successfully. "
}