Share via

Work with asynchronous class notebooks

  • Article

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"
}

See also