Work with class notebooks

Article
08/21/2018

Applies to: Enterprise notebooks on Office 365

Schools, colleges, and universities worldwide use class notebooks to help promote productivity, engagement, and collaboration. You can use class notebooks for every class, project, term, and assignment.

You can use the classNotebooks endpoint to perform common tasks for class notebooks, such as creating class notebooks and adding or removing students.

Note

The OneNote API provides the classNotebooks endpoint for operations that are specific to class notebooks.

Construct the request URI

To construct the request URI, start with the service root URL for your platform:

Notebooks on OneDrive for Business

https://www.onenote.com/api/v1.0/me/notes/

https://www.onenote.com/api/v1.0/users/{id}/notes/

SharePoint site notebooks

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

Unified group notebooks

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/

Append the classNotebooks endpoint, followed a resource path, as needed:

Create class notebooks

../classNotebooks[?omkt,sendemail]

Update a class notebook

../classNotebooks/{notebook-id}

Get one or more class notebooks

../classNotebooks

../classNotebooks/{notebook-id}

Delete a class notebook

../classNotebooks/{notebook-id}

Add students or teachers

../classNotebooks/{notebook-id}/students

../classNotebooks/{notebook-id}/teachers

Remove students or teachers

../classNotebooks/{notebook-id}/students/{student-id}

../classNotebooks/{notebook-id}/teachers/{teacher-id}

Insert sections

../classNotebooks/{notebook-id}/copySectionsToContentLibrary

Your full request URI will look something like these examples:

https://www.onenote.com/api/v1.0/me/notes/classNotebooks/{id}/teachers/{id}

https://www.onenote.com/api/v1.0/users/{id}/notes/classNotebooks/{id}/students

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/classNotebooks

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/classNotebooks/{id}

https://www.onenote.com/api/v1.0/me/notes/classNotebooks/{id}/copySectionsToContentLibrary

Note

Learn more about the service root URL.

Create class notebooks

To create a class notebook, send a POST request to the classNotebooks endpoint.

POST ../classNotebooks[?omkt,sendemail]

In the message body, send a JSON object with the class notebook creation parameters.

{
    "name": "notebook-name",
    "studentSections": [ 
        "section1-name", 
        "section2-name"
    ],
    "teachers": [
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        }
    ],
    "students": [
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group" 
        },
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        },
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        }
   ], 
   "hasTeacherOnlySectionGroup": true
}

Parameter	Description
name	The name of the notebook.
studentSections	An array containing one or more section names. These sections are created in each student's section group.
teachers	An array containing one or more principal objects.
students	An array containing one or more principal objects. A section group is created for each student.
hasTeacherOnlySectionGroup	`true` to create a Teacher Only section group that's visible to teachers only.
omkt	URL query parameter that specifies the language for the notebook. Default is `en-us`. Example: `?omkt=es-es`
sendemail	URL query parameter that specifies whether to send an email notification when the notebook is created to the teachers and students assigned to the notebook. Default is `false`.

Teachers and students are represented by principal objects, which contain the following properties:

Parameter	Description
id	The Office 365 user principal name. See the Azure AD Graph API documentation to learn more about users and groups.
principalType	`Person` or `Group`

Supported languages

You can use the omkt={language-code} URL query parameter to create a class notebook in a specific language. For example:

POST ../classNotebooks?omkt=de-de

The following language codes are supported. The default is en-us.

Code	Language
bg-bg	Български (България)
cs-cz	Čeština (Česká republika)
da-dk	Dansk (Danmark)
de-de	Deutsch (Deutschland)
el-gr	Ελληνικά (Ελλάδα)
en-us	English (United States)
es-es	Español (España)
et-ee	Eesti (Eesti)
fi-fi	Suomi (Suomi)
fr-fr	Français (France)
hi-in	हिंदी (भारत)
hr-hr	Hrvatski (Hrvatska)
hu-hu	Magyar (Magyarország)
id-id	Bahasa Indonesia (Indonesia)
it-it	Italiano (Italia)
ja-jp	日本語 (日本)
kk-kz	Қазақ (Қазақстан)
ko-kr	한국어 (대한민국)
lt-lt	Lietuvių (Lietuva)
lv-lv	Latviešu (Latvija)
ms-my	Bahasa Melayu (Asia Tenggara)
nb-no	Norsk (Norge)
nl-nl	Nederlands (Nederland)
pl-pl	Polski (Polska)
pt-br	Português (Brasil)
pt-pt	Português (Portugal)
ro-ro	Română (România)
ru-ru	Русский (Россия)
sk-sk	Slovenčina (Slovenská republika)
sl-si	Slovenski (Slovenija)
sr-Latn-RS	Srpski (Rep. Srbija i Rep. Crna Gora)
sv-se	Svenska (Sverige)
th-th	ไทย (ไทย)
tr-tr	Türkçe (Türkiye)
uk-ua	Українська (Україна)
vi-vn	Tiếng Việt (Việt Nam)
zh-cn	简体中文 (中国)
zh-tw	繁體中文 (台灣)

Example

The following request creates a class notebook named Math 101.

POST ../v1.0/users/{teacher-id}/notes/classNotebooks?sendemail=true
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

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

This creates a class notebook with four student section groups, each containing a Handouts, Class Notes, Homework, and Quizzes section. The section group created for each student is only accessible by the student and the teacher. It also creates a Teacher Only section group that's only visible to the teacher. The sendemail=true query parameter specifies to send an email notification to the teacher and students when the notebook is created.

Request and response information

The following information applies to POST /classNotebooks requests.

Request data	Description
Protocol	All requests use the SSL/TLS HTTPS protocol.
Authorization header	`Bearer {token}`, where {token} is a valid OAuth 2.0 access token for your registered app. If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Content-Type header	`application/json`
Accept header	`application/json`
Permission scope	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All

Response data	Description
Success code	A 201 HTTP status code.
Response body	An OData representation of the new notebook in JSON format. In addition to regular notebook properties, class notebooks also have the following properties: studentSections. The student sections in the notebooks. teachers. The teachers that can access the notebook. students. The students that can access the notebook. hasTeacherOnlySectionGroup. `true` if the notebook contains a Teacher Only section group, otherwise `false`.
Errors	If the request fails, the API returns errors in the `@api.diagnostics` object in the response body.
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.

Update class notebooks

To update a class notebook, send a PATCH request to the classNotebooks/{notebook-id} endpoint.

Note

Currently, only the hasTeacherOnlySectionGroup property can be updated in a PATCH request.

PATCH ../classNotebooks/{notebook-id}

In the message body, send a JSON object with the update parameter.

{
    "hasTeacherOnlySectionGroup": true
}

Parameter	Description
hasTeacherOnlySectionGroup	`true` to add a Teacher Only section group that's visible to teachers only. `false` is not supported.

See these methods for other ways to change class notebooks: Add students or teachers, Remove students or teachers, Insert sections.

Example

The following request adds a Teacher Only section group to the specified class notebook.

PATCH ../v1.0/users/{teacher-id}/notes/classNotebooks/{notebook-id}
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "hasTeacherOnlySectionGroup": true
}

The new Teacher Only section group is visible to teachers only.

Request and response information

The following information applies to PATCH ../classNotebooks/{notebook-id} requests.

Request data	Description
Protocol	All requests use the SSL/TLS HTTPS protocol.
Authorization header	`Bearer {token}`, where {token} is a valid OAuth 2.0 access token for your registered app. If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Content-Type header	`application/json`
Accept header	`application/json`
Permission scope	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All

Response data	Description
Success code	A 204 HTTP status code.
Errors	If the request fails, the API returns errors in the response body.
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.

Get class notebooks

To get one or more class notebooks, send a GET request to the classNotebooks endpoint.

Get one or more class notebooks

GET ../classNotebooks[?filter,orderby,select,top,skip,expand,count]

Get a specific class notebook

GET ../classNotebooks/{notebook-id}[?select,expand]

Notebooks can expand the teachers and students properties. The default sort order is name asc.

Class notebooks are also returned for GET /notebooks requests, but the results won't include any class notebook-specific properties.

Example

The following request gets class notebooks that were created since January 1, 2016.

GET ../v1.0/users/{teacher-id}/notes/classNotebooks?filter=createdTime%20ge%202016-01-01 
Authorization: Bearer {token}
Accept: application/json

To learn more about getting notebooks, including supported query string options and examples, see Get OneNote content and structure.

Request and response information

The following information applies to GET /classNotebooks requests.

Request data	Description
Protocol	All requests use the SSL/TLS HTTPS protocol.
Authorization header	`Bearer {token}`, where {token} is a valid OAuth 2.0 access token for your registered app. If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Accept header	`application/json`
Permission scope	Notes.Read, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All

Response data	Description
Success code	A 200 HTTP status code.
Response body	An OData representation of the class notebooks in JSON format. In addition to regular notebook properties, class notebooks also have the following properties: studentSections. The student sections in the notebooks. teachers. The teachers that can access the notebook. student. The students that can access the notebook. hasTeacherOnlySectionGroup. `true` if the notebook contains a Teacher Only section group, otherwise `false`.
Errors	If the request fails, the API returns errors in the `@api.diagnostics` object in the response body.
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.

Delete class notebooks

To delete a class notebook, send a DELETE request to the classNotebooks/{notebook-id} endpoint.

DELETE ../classNotebooks/{notebook-id}

Example

The following request deletes the specified class notebook.

DELETE ../v1.0/users/{teacher-id}/notes/classNotebooks/{notebook-id} 
Authorization: Bearer {token}
Accept: application/json

Request and response information

The following information applies to DELETE ../classNotebooks/{notebook-id} requests.

Request data	Description
Protocol	All requests use the SSL/TLS HTTPS protocol.
Authorization header	`Bearer {token}`, where {token} is a valid OAuth 2.0 access token for your registered app. If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Accept header	`application/json`
Permission scope	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All

Response data	Description
Success code	A 204 HTTP status code.
Errors	If the request fails, the API returns errors in the response body.
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.

Add students and teachers

Adding teachers and students 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, send a POST request to the appropriate endpoint.

Add a student

POST ../classNotebooks/{notebook-id}/students

Add a teacher

POST ../classNotebooks/{notebook-id}/teachers

Send a JSON principal object in the message body. You can add one student or one teacher per request.

{
    "id": "alias@tenant",
    "principalType": "Person-or-Group"
}

Teachers and students are represented by principal objects, which contain the following properties:

Parameter	Description
id	The Office 365 user principal name. See the Azure AD Graph API documentation to learn more about users and groups.
principalType	`Person` or `Group`

Example

The following request adds a teacher to the specified class notebook.

POST ../v1.0/users/{teacher-id}/notes/classNotebooks/{notebook-id}/teachers 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "id": "teacher2@contoso.com",
    "principalType": "Person"
}

Request and response information

The following information applies to POST /students and POST /teachers requests.

Request data	Description
Protocol	All requests use the SSL/TLS HTTPS protocol.
Authorization header	`Bearer {token}`, where {token} is a valid OAuth 2.0 access token for your registered app. If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Content-Type header	`application/json`
Accept header	`application/json`
Permission scope	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All

Response data	Description
Success code	A 201 HTTP status code.
Response body	The student or teacher that was added.
Errors	If the request fails, the API returns errors in the `@api.diagnostics` object in the response body.
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.

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, send a DELETE request to the appropriate endpoint.

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 student from the specified class notebook.

DELETE ../v1.0/users/{teacher-id}/notes/classNotebooks/{notebook-id}/students/{student-id} 
Authorization: Bearer {token}
Accept: application/json

Request and response information

The following information applies to DELETE /students and DELETE /teachers requests.

Request data	Description
Protocol	All requests use the SSL/TLS HTTPS protocol.
Authorization header	`Bearer {token}`, where {token} is a valid OAuth 2.0 access token for your registered app. If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Accept header	`application/json`
Permission scope	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All

Response data	Description
Success code	A 204 HTTP status code.
Errors	If the request fails, the API returns errors in the `@api.diagnostics` object in the response body.
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.

Insert sections

Use copySectionsToContentLibrary to copy specific sections from Office 365 notebooks and insert them into the Content Library of a class notebook. A Content Library is a section group inside the class notebook that has Read/Write permissions for teachers and Read permission for students.

To insert sections into a class notebook, send a POST request to the copySectionsToContentLibrary endpoint of the target class notebook. For example:

POST ../classNotebooks/{notebook-id}/copySectionsToContentLibrary

In the message body, send a JSON object with the sectionIds parameter.

{
    "sectionIds": [
        "section1-id", 
        "section2-id",
        ...
    ]
}

Parameter	Description
sectionIds	An array that contains the IDs of the sections that you want to insert into the class notebook.

The user must have access to the target sections and notebook (owned or shared). All targets must be in the same tenant.

Example

The following request inserts two sections into the Content Library of the specified class notebook.

POST ../v1.0/me/notes/classNotebooks/{notebook-id}/copySectionsToContentLibrary
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "sectionIds": [
        "1-85ba33b1-4959-4102-8dcd-d98e4e56e56f", 
        "1-8ba42j81-4959-4102-8dcd-d98e4e94s62ef"
    ]
}

Request and response information

The following information applies to POST /copySectionsToContentLibrary requests.

Request data	Description
Protocol	All requests use the SSL/TLS HTTPS protocol.
Authorization header	`Bearer {token}`, where {token} is a valid OAuth 2.0 access token for your registered app. If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Content-Type header	`application/json`
Accept header	`application/json`
Permission scope	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All

Response data	Description
Success code	A 201 HTTP status code.
Errors	If the create request fails, the API returns errors in the response body.
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.

Distribute page to student

To distribute a OneNote page to a student, send a POST request to the classNotebooks endpoint. The following action is only available for the unified group notebooks.

POST ../groups/{id}/notes/classnotebooks/{id}/pages('{id}')/Microsoft.OneNote.Api.DistributePageToStudent

In the message body, send a JSON object with the DistributePageToStudent parameters.

{
"studentUserPrincipalName": "alias@tenant",
"lockStartDate": "DateTimeOffset",
"targetSectionName": "section-name",
"assignmentId":"assignment-id",
"ignoreIfStudentPageExists":true
}

Parameter	Description
studentUserPrincipalName	The Office 365 user principal name. To learn more about users, see the Azure AD Graph API documentation.
lockStartDate	The lock start date of type DateTimeOffset to be set on the distributed page. Student page will be read-only when the time reaches the lock start date. For more information about page lock, see Use page locking in Class Notebook.
targetSectionName	The page is copied into the student's section. If the student's section does not exist, it will be created.
assignmentId	(optional) The assignment id to be set on the distributed page. If the property is set, there should be one page published for one assignment id, and the lockStartDate would be the assignment due date.
ignoreIfStudentPageExists	`true` to ignore copying the page if there is another page with the same assignment id.

Response data	Description
Success code	A 200 HTTP status code.
Response body	An OData representation of the result in JSON format. The value returned is the student page id that got copied.
Errors	If the request fails, the API returns errors in the @api.diagnostics object in the response body.
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.

Example

POST https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b60795e6-0345-4893-a878-ce365d246651/pages('1-b168ad794f2f469b8de2696dd737d2b3!69-d39b2f49-a8fc-4c92-894b-32a4c27595bb')/Microsoft.OneNote.Api.DistributePageToStudent
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
{
"studentUserPrincipalName": "student1@contoso.net",
"lockStartDate": "2018-12-15T23:17:16Z",
"targetSectionName": "quizes",
"assignmentId":"4cb4f3d3-d7fd-463b-beb5-526dafb7241d",
"ignoreIfStudentPageExists":true
}

Update the page lock start date

To update the lock start date of a OneNote page, send a PATCH request to the pages endpoint.

For more information about page lock, see Use page locking in Class Notebook.

PATCH ../pages/{page-id}

In the message body, send a JSON object with the following request data.

Request data	Description
blockEditsInClientStartDate	A DateTimeOffset structure of when the page will be locked for edit. To clear the lock start date, set the property to null; hence, it will be dropped from the page.

Response data	Description
Success code	A 204 HTTP No Content status code.
Errors	If the request fails, the API returns errors in the @api.diagnostics object in the response body.
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.

Example

https://www..onenote.com/api/v1.0/me/notes/pages/1-126bc4155684422c827e1682b1e5f2ed!62-3a2cebc9-3121-4162-b84a-07e61671e653
 
{
“blockEditsInClientStartDate”:"2018-02-25T15:17:16.0938811-08:00" 
}

Get page lock start date

To get the lock start date that is set on the page, send a GET request to the API pages endpoint to get the page(metadata) with a query parameter blockEditsInClientStartDate=true.

GET ../pages/{page-id}?blockEditsInClientStartDate=true

For more information about how to query a page, see Resource paths for GET requests.

For more information about page lock, see Use page locking in Class Notebook.

Response data	Description
Success code	A 200 HTTP status code.
Response body	An OData representation of the page in JSON format. It includes the value of the blockEditsInClientStartDate property.
Errors	If the request fails, the API returns errors in the @api.diagnostics object in the response body.
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.

Example

GET https://www.onenote.com/api/v1.0/me/notes/pages/1-126bc4155684422c827e1682b1e5f2ed!62-3a2cebc9-3121-4162-b84a-07e61671e653?blockEditsInClientStartDate=true
 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Response

{
…
“blockEditsInClientStartDate”:”1985-02-25T23:17:16Z”
…
}

Update membership

UpdateMembership syncs a default class notebook of a unified group with its membership.

Unified group owners will be added as teachers to a class notebook, and members will be added as students to a class notebook.

To sync the default class notebook membership with a unified group, send a POST request to the classNotebooks endpoint. The following action is only available for the unified group default notebook.

POST ../classnotebooks/Microsoft.OneNote.Api.UpdateMembership

Response data	Description
Success code	A 204 HTTP No Content status code.
Errors	If the request fails, the API returns errors in the @api.diagnostics object in the response body.
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.

Example

The following example syncs a default class notebook of a unified group id.

Request

POST https://www.onenote.com/api/v1.0/myOrganization/groups/1d13f814-83e5-4c11-8294-53bf40defd91/notes/classnotebooks/ Microsoft.OneNote.Api.UpdateMembership
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Repair a class notebook

To repair a class notebook, send a POST request to the classNotebooks endpoint.

POST ../classnotebooks/{notebook-id}/Microsoft.OneNote.Api.RepairNotebook

The odata action reads the list of students and teachers from the class notebook metadata. It then reapplies students' permissions to their section groups, _Content Library and _Collaboration Space. It also reapplies teachers' permissions to Students, _Content Library, _Collaboration Space, and _teacher only section groups.

For unified groups, it does not refresh group membership; for that, use the UpdateMembership action instead.

POST ../classnotebooks/{notebook-id}/Microsoft.OneNote.Api.RepairNotebook
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Response data	Description
Success code	A 204 HTTP No Content status code.
Errors	If the request fails, the API returns errors in the @api.diagnostics object in the response body.
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.

Example

POST https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b60795e6-0345-4893-a878-ce365d246651/Microsoft.OneNote.Api.RepairNotebook

Construct the OneNote service root URL

The OneNote service root URL uses the following format for all calls to the OneNote API.

https://www.onenote.com/api/{version}/{location}/notes/

The version segment in the URL represents the version of the OneNote API that you want to use.

Use v1.0 for stable production code.
Use beta to try out a feature that's in development. Features and functionality in beta may change, so you shouldn't use it in your production code.

The location segment in the URL represents the location of the notebooks that you want to access:

Notebooks on OneDrive for Business
- Use me for OneNote content that’s owned by the current user.
- Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. Use the Azure AD Graph API to get user IDs.
SharePoint site notebooks
- Team sites and other SharePoint sites can contain OneNote notebooks in their document libraries.
- Use myOrganization/siteCollections/{id}/sites/{id} for OneNote content in a site in the tenant that the current user is logged into. Only the current tenant is supported, accessed using the myOrganization keyword. Learn how to get site IDs.
Unified group notebooks
- Unified groups (also called Office 365 groups) are part of the Office 365 connected experience. Group members can share notebooks, files, and email.
- Use myOrganization/groups/{id} for OneNote content in the specified group that the current user is a member of. Unified groups are the only supported group type. Use the Azure AD Graph API to get group IDs.

Use the FromUrl method to get the site collection and site IDs

You can use the FromUrl method to get the site collection and site IDs for a specified absolute site URL. You should make this call only when needed, and then store the values for future use.

The format of the site URL depends on your configuration, for example https://domain.sharepoint.com/site-a or https://domain.com/sites/site-a.

Example request

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')

Authorization: Bearer {token}

Accept: application/json

Example response

{"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata", "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5", "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"}

Requirements for using FromUrl and working with SharePoint site notebooks:

You can only create OneNote notebooks, section groups, sections, and pages on sites that have a default document library. (Some site templates don't create a default document library.) However, GET requests return OneNote content from all document libraries on the site.
The OneNote service root URL is immutable, meaning you can't use a SharePoint REST API site path and then tack the notes endpoint onto it.
The user on whose behalf you're calling must be a member of the site.
FromUrl works only with sites that have been indexed. It may take several hours to index a new site.

Share via

Work with class notebooks

Construct the request URI

Create class notebooks

Supported languages

Example

Request and response information

Update class notebooks

Example

Request and response information

Get class notebooks

Get one or more class notebooks

Get a specific class notebook

Example

Request and response information

Delete class notebooks

Example

Request and response information

Add students and teachers

Add a student

Add a teacher

Example

Request and response information

Remove students and teachers

Remove a student

Remove a teacher

Example

Request and response information

Insert sections

Example

Request and response information

Distribute page to student

Example

Update the page lock start date

Example

Get page lock start date

Example

Response

Update membership

Example

Request

Repair a class notebook

Example

Construct the OneNote service root URL

Use the FromUrl method to get the site collection and site IDs

Example request

Example response

See also

Additional resources