-->
Applies to: Enterprise notebooks on Office 365
Schools, colleges, and universities worldwide use staff notebooks to help promote productivity, engagement, and collaboration.
OneNote Staff Notebooks have a personal workspace for every staff member or teacher, a content library for shared information, and a collaboration space for everyone to work together, all within one powerful notebook. Staff Notebook Sign In Sign in with your Office 365 account from your school to get started. This guide goes into more detail about how you can use OneNote Staff Notebook to work together with colleagues, distribute important materials schoolwide, and provide personalized, professional feedback to your staff. This guide shows how to create a OneNote Staff Notebook, add custom sections to staff members’ private workspaces, and add or remove notebook users and co-owners. Professional Learning Communities (PLC) — We think that OneNote Staff Notebooks are a great tool to enable Professional Learning Communities (PLC) in schools. By using the simple setup, the leader of the PLC ('Staff Leader') can quickly set up a notebook in which.
You can use the staffNotebooks endpoint to perform common tasks for staff notebooks, such as creating staff notebooks and adding or removing leaders or members.
Note
The OneNote API provides the staffNotebooks endpoint for operations that are specific to staff 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 staffNotebooks endpoint, followed a resource path, as needed:
./staffNotebooks[?omkt,sendemail]./staffNotebooks/{notebook-id}./staffNotebooks./staffNotebooks/{notebook-id}./staffNotebooks/{notebook-id}./staffNotebooks/{notebook-id}/members./staffNotebooks/{notebook-id}/leaders./staffNotebooks/{notebook-id}/members/{member-id}./staffNotebooks/{notebook-id}/leaders/{leader-id}./staffNotebooks/{notebook-id}/copySectionsToContentLibrary
Your full request URI will look something like these examples:
https://www.onenote.com/api/v1.0/me/notes/staffNotebooks/{id}/leaders/{id}
https://www.onenote.com/api/v1.0/users/{id}/notes/staffNotebooks/{id}/members
https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/staffNotebooks
https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/staffNotebooks/{id}
https://www.onenote.com/api/v1.0/me/notes/staffNotebooks/{id}/copySectionsToContentLibrary
Create staff notebooks
To create a staff notebook, send a POST request to the staffNotebooks endpoint.
POST ./staffNotebooks[?omkt,sendemail]
In the message body, send a JSON object with the staff notebook creation parameters.
| Parameter | Description |
|---|---|
| name | The name of the notebook. |
| memberSections | An array containing one or more section names. These sections are created in each member's section group. |
| leaders | An array containing one or more principal objects. |
| members | An array containing one or more principal objects. A section group is created for each member. |
| hasLeaderOnlySectionGroup | true to create a Leader Only section group that's visible to leaders 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 leaders and members assigned to the notebook. Default is false. |
Leaders and members 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 staff notebook in a specific language. For example:
POST ./staffNotebooks?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 staff notebook named Staff Meetings.
This creates a staff notebook with four member section groups, each containing a Handouts, Staff Notes, and Meeting Summaries section. The section group created for each member is only accessible by the member and the leader. It also creates a Leader Only section group that's only visible to the leader. The sendemail=true query parameter specifies to send an email notification to the leader and members when the notebook is created.
Request and response information
The following information applies to POST /staffNotebooks requests.
| Request data | Description |
|---|---|
| Protocol | All requests use the SSL/TLS HTTPS protocol. |
| Authorization header |
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, staff notebooks also have the following properties:
|
| 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 staff notebooks
To update a staff notebook, send a PATCH request to the staffNotebooks/{notebook-id} endpoint.
Note
Currently, only the hasLeaderOnlySectionGroup property can be updated in a PATCH request.
PATCH ./staffNotebooks/{notebook-id}
In the message body, send a JSON object with the update parameter.
| Parameter | Description |
|---|---|
| hasLeaderOnlySectionGroup | true to add a Leader Only section group that's visible to leaders only. false is not supported. |
See these methods for other ways to change staff notebooks: Add members or leaders, Remove members or leaders, Insert sections.
Example
The following request adds a Leader Only section group to the specified staff notebook.
The new Leader Only section group is visible to leaders only.
Request and response information
The following information applies to PATCH ./staffNotebooks/{notebook-id} requests.
| Request data | Description |
|---|---|
| Protocol | All requests use the SSL/TLS HTTPS protocol. |
| Authorization header |
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 staff notebooks
To get one or more staff notebooks, send a GET request to the staffNotebooks Download whatsapp os. endpoint.
Get one or more staff notebooks
GET ./staffNotebooks[?filter,orderby,select,top,skip,expand,count]
Get a specific staff notebook
GET ./staffNotebooks/{notebook-id}[?select,expand]
Notebooks can expand the leaders and members properties. The default sort order is name asc. Best macbook apps 2015.
Staff notebooks are also returned for GET /notebooks requests, but the results won't include any staff notebook-specific properties.
Example
The following request gets staff notebooks that were created since January 1, 2016.
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 /staffNotebooks requests.
| Request data | Description |
|---|---|
| Protocol | All requests use the SSL/TLS HTTPS protocol. |
| Authorization header |
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 staff notebooks in JSON format. In addition to regular notebook properties, staff notebooks also have the following properties:
|
| 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 staff notebooks
To delete a staff notebook, send a DELETE request to the staffNotebooks/{notebook-id} endpoint.
DELETE ./staffNotebooks/{notebook-id}
Example
The following request deletes the specified staff notebook.
Request and response information
The following information applies to DELETE ./staffNotebooks/{notebook-id} requests.
| Request data | Description |
|---|---|
| Protocol | All requests use the SSL/TLS HTTPS protocol. |
| Authorization header |
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 members and leaders
Adding leaders and members gives them access to the staff notebook. Adding a member also creates a member section group. This section group is only accessible by the member and the leader, and contains the member sections that are defined for the notebook.
To add a member or leader to a staff notebook, send a POST request to the appropriate endpoint.
Add a member
POST ./staffNotebooks/{notebook-id}/members
Add a leader
POST ./staffNotebooks/{notebook-id}/leaders
Send a JSON principal object in the message body. You can add one member or one leader per request.
Leaders and members 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 leader to the specified staff notebook.
Request and response information
The following information applies to POST /members and POST /leaders requests.
| Request data | Description |
|---|---|
| Protocol | All requests use the SSL/TLS HTTPS protocol. |
| Authorization header |
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 |
Microsoft Teams Staff Notebook
| Response data | Description |
|---|---|
| Success code | A 201 HTTP status code. |
| Response body | The member or leader 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 members and leaders
Removing members and leaders from a staff notebook revokes their access to the notebook, but doesn't delete any content.
Onenote Staff Notebook Staff Leader
To remove a member or leader from a staff notebook, send a DELETE request to the appropriate endpoint.
Remove a member
DELETE ./staffNotebooks/{notebook-id}/members/{member-id}
Remove a leader
DELETE ./staffNotebooks/{notebook-id}/leaders/{leader-id}
You can remove one member or one leader per request.
Example
The following request removes the specified member from the specified staff notebook.
Request and response information
The following information applies to DELETE /members and DELETE /leaders requests.
| Request data | Description |
|---|---|
| Protocol | All requests use the SSL/TLS HTTPS protocol. |
| Authorization header |
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 staff notebook. A Content Library is a section group inside the staff notebook that has Read/Write permissions for leaders and Read permission for members.
To insert sections into a staff notebook, send a POST request to the copySectionsToContentLibrary endpoint of the target staff notebook. For example:
POST ./staffNotebooks/{notebook-id}/copySectionsToContentLibrary
In the message body, send a JSON object with the sectionIds parameter.
| Parameter | Description |
|---|---|
| sectionIds | An array that contains the IDs of the sections that you want to insert into the staff notebook. |
The user must have access to the target sections and notebook (owned or shared). All targets must be in the same tenant.
Onenote Staff Notebook For Education
Example
The following request inserts two sections into the Content Library of the specified staff notebook.
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 |
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. |
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.0for stable production code.Use
betato 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
mefor 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 themyOrganizationkeyword. 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
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
notesendpoint 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.
See also
- OneNote staff notebooks (overview and features)