Work with asynchronous class notebooks
Applies to: Enterprise notebooks on Office 365
Schools, colleges, and universities worldwide use OneNote class notebooks to help promote productivity, engagement, and collaboration. You can use class notebooks for every class, project, term, and assignment.
The classNotebooks endpoint is used to perform common tasks for class notebooks, such as creating class notebooks, as well as adding or removing students in asynchronous calls.
Note
The OneNote API provides the classNotebooks endpoint for operations that are specific to class notebooks.
Asynchronous API
To make asynchronous calls to the classNotebooks endpoint, send a request with a header Prefer: respond-async.
Response
| Response data | Description |
|---|---|
| Success code | A 202 status HTTP status code. |
| Location header | The URL to poll for the status of the operation. Polling the operation endpoint returns an OperationModel object that contains the status of the operation and other information. |
| X-CorrelationId header | A GUID that uniquely identifies the request. You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues. |
Operation model
| Operation model | Description |
|---|---|
| Id | The ID of the operation. |
| Status | The status can be the following: completed, running, not started, or failed. - If completed, the resourceLocation property contains the resource endpoint for the new classNotebook. - If running, the createdDateTime and lastActionDateTime show when the request was created and when it ran last. - If failed, the error and @api.diagnostics properties provide error information. |
| createdDateTime | Shows when the request was created. |
| lastActionDateTime | Shows when the request was created and when it ran last. |
| resourceLocation | The endpoint for the resource. |
| resourceId | The ID of the resource. |
Construct the request URI
To construct the request URI, see Construct the request URI in the topic Work with class notebooks.
Create class notebooks
To create a class notebook in an asynchronous call, send a POST request to the classNotebooks endpoint with the header Prefer: respond-async.
POST ../classNotebooks
For the message body and the JSON object with the class notebook creation parameters, see Create class notebooks.
Example
The following request creates a class notebook named Math 101.
Request
POST https://www.onenote.com/v1.0/me/notes/classNotebooks?sendemail=true
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"name": "Math 101",
"studentSections": [
"Handouts",
"Class Notes",
"Homework",
"Quizzes"
],
"teachers": [
{
"id": "teacher1@contoso.com",
"principalType": "Person"
}
],
"students": [
{
"id": "student1@contoso.com",
"principalType": "Person"
},
{
"id": "student2@contoso.com",
"principalType": "Person"
},
{
"id": "student3@contoso.com",
"principalType": "Person"
},
{
"id": "student4@contoso.com",
"principalType": "Person"
}
],
"hasTeacherOnlySectionGroup": true
}
Response
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/classnotebook-ee91aafb-5685-4357-9465-77d611ef064c
Poll the operation Location endpoint to get the status of the create class operation.
Request
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebook-ee91aafb-5685-4357-9465-77d611ef064c
Response
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebook-ee91aafb-5685-4357-9465-77d611ef064c",
"status":"completed",
"createdDateTime":"2018-06-01T23:44:29.349Z",
"lastActionDateTime":"2018-06-01T23:44:29.349Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-cb6e0bf6-1185-4daa-80a1-ded42ca1708e",
"resourceId":"1-cb6e0bf6-1185-4daa-80a1-ded42ca1708e"
}
Add students and teachers
Adding students and teachers gives them access to the class notebook. Adding a student also creates a student section group. This section group is only accessible by the student and the teacher, and contains the student sections that are defined for the notebook.
To add a student or teacher to a class notebook in an asynchronous call, send a POST request to the appropriate endpoint with a header Prefer: respond-async.
Add a student
POST ../classNotebooks/{notebook-id}/students
Add a teacher
POST ../classNotebooks/{notebook-id}/teachers
For the message body and the JSON object with the class notebook creation parameters, see Add students or teachers.
Example
The following request adds a teacher to the specified class notebook.
Request
POST https://www.onenote/api/v1.0/me/notes/classNotebooks/ 1-b68a21fd-cdb3-41f1-a566-0772872a8a0c//teachers
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"id": "teacher2@contoso.com",
"principalType": "Person"
}
Response
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9
Poll the operation Location endpoint to get the status of the add teacher operation.
Request
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9
Response
{
"@odata.context":"https://www.onenote/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9",
"status":"completed",
"createdDateTime":"2018-06-12T22:23:47.548Z",
"lastActionDateTime":"2018-06-12T22:23:47.548Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net",
"resourceId":"teacher2@contoso.net"
}
Remove students and teachers
Removing students and teachers from a class notebook revokes their access to the notebook, but doesn't delete any content. To remove a student or teacher from a class notebook in an asynchronous call, send a DELETE request to the appropriate endpoint with the header Prefer: respond-async.
Remove a student
DELETE ../classNotebooks/{notebook-id}/students/{student-id}
Remove a teacher
DELETE ../classNotebooks/{notebook-id}/teachers/{teacher-id}
You can remove one student or one teacher per request.
Example
The following request removes the specified teacher from the specified class notebook.
Request
DELETE https://www.onenote.com/api/v1.0/me /notes/classNotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net
Authorization: Bearer {token}
Accept: application/json
Prefer: respond-async
Response
HTTP/1.1 202 Accepted
Location: https://www.onenotecom/api/v1.0/me/notes/operations/classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a
Poll the operation Location endpoint to get the status of the delete teacher operation.
Request
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a
Response
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a",
"status":"completed",
"createdDateTime":"2018-06-12T22:40:06.708Z",
"lastActionDateTime":"2018-06-12T22:40:06.708Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net",
"resourceId":"teacher2@contoso.net"
}
Transfer notebook
To transfer a notebook from one teacher to another teacher in an asynchronous call, send a POST request to the classNotebooks endpoint.
POST ../classnotebooks/{notebook-id}/Microsoft.OneNote.Api.classnotebooktransfer
This API requires tenant administrative privileges.
In the message body, send the JSON object with transfer class notebook parameters.
{
"ClassNotebookTransfer" : {
"sourceTeacher": {
"principalType":"Person",
"id":"alias@tenant"
},
"destinationTeacher" : {
"principalType":"Person",
"id":"alias@tenant"
},
"destinationNotebookName": "notebook-name"
}
}
| Parameter | Description |
|---|---|
| destinationNotebookName | The name of the notebook at the destination. |
| destinationTeacher | A principal object. |
| sourceTeacher | A principal object. |
The source and destination Teacher are represented by a principal object that contains the following parameters.
| Parameter | Description |
|---|---|
| id | The Office 365 user principal name. To learn more about users and groups, see the Azure AD Graph API documentation. |
| principalType | Person |
Example
The following example transfers a class notebook named Math 101.
Request
POST https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-9a43afaa-7dc9-4405-b661-b735ebf722a0/Microsoft.OneNote.Api.classnotebooktransfer
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"ClassNotebookTransfer" : {
"sourceTeacher": {
"principalType":"Person",
"id":"teacher1@contososd.org"
},
"destinationTeacher" : {
"principalType":"Person",
"id":"teacher2@contososd.org"
},
"destinationNotebookName": "Math 101"
}
}
Response
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/transfer-9a43afaa-7dc9-4405-b661-b735ebf722a0
Poll the operation Location endpoint to get the status of the transfer notebook.
Request
GET https://www.onenote.com/api/v1.0/me/notes/operations/transfer-9a43afaa-7dc9-4405-b661-b735ebf722a0
Response
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"transfer9a43afaa-7dc9-4405-b661-b735ebf722a0",
"status":"completed",
"createdDateTime":"0001-01-01T00:00:00Z",
"lastActionDateTime":"0001-01-01T00:00:00Z",
"resourceId":"1-6e0cebcb-b589-4632-8b31-1ffe804652e0"
}
Update membership
To update the membership of a class notebook in an asynchronous call, send a POST request to the classNotebooks endpoint with a header Prefer: respond-async.
POST
../groups/{groupId}/classnotebooks/Microsoft.OneNote.Api.UpdateMembership
For the message body and the JSON object with the update membership action parameters, see the Update membership section in Work with class notebooks.
Example
The following example syncs the default class notebook of a unified group.
Request
POST https://www.onenote.com/api/v1.0/myOrganization/groups/1d13f814-83e5-4c11-8294-53bf40defd91/notes/classnotebooks/classnotebooks/Microsoft.OneNote.Api.UpdateMembership
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
Response
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/updatemembership-9a43afaa-7dc9-4405-b661-b735ebf722a0
Poll the operation Location endpoint to get the status of the update membership of a class notebook.
Request
GET https://www.onenote.com/api/v1.0/me/notes/operations/updatemembership-9a43afaa-7dc9-4405-b661-b735ebf722a0
Response
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"updateMembership-9a43afaa-7dc9-4405-b661-b735ebf722a0",
"status":"completed",
"createdDateTime":"0001-01-01T00:00:00Z",
"lastActionDateTime":"0001-01-01T00:00:00Z",
"resourceId":"1-6e0cebcb-b589-4632-8b31-1ffe804652e0"
}