Work with staff notebooks

  • Article

Applies to: Enterprise notebooks on Office 365

Schools, colleges, and universities worldwide use staff notebooks to help promote productivity, engagement, and collaboration.

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

  1. 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/

  2. Append the staffNotebooks endpoint, followed a resource path, as needed:

    Create staff notebooks

    ../staffNotebooks[?omkt,sendemail]

    Update a staff notebook

    ../staffNotebooks/{notebook-id}

    Get one or more staff notebooks

    ../staffNotebooks

    ../staffNotebooks/{notebook-id}

    Delete a staff notebook

    ../staffNotebooks/{notebook-id}

    Add members or leaders

    ../staffNotebooks/{notebook-id}/members

    ../staffNotebooks/{notebook-id}/leaders

    Remove members or leaders

    ../staffNotebooks/{notebook-id}/members/{member-id}

    ../staffNotebooks/{notebook-id}/leaders/{leader-id}

    Insert sections

    ../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

Note

Learn more about the service root URL.

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.

{
    "name": "notebook-name",
    "memberSections": [ 
        "section1-name", 
        "section2-name"
    ],
    "leaders": [
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        }
    ],
    "members": [
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group" 
        },
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        },
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        }
   ], 
   "hasLeaderOnlySectionGroup": true
}
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.

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

{
    "name": "Staff Meetings",
    "memberSections": [
        "Staff Notes",
        "Meeting Summaries",
    ],
    "leaders": [
        {
            "id": "leader1@contoso.com",
            "principalType": "Person"
        }
    ],
    "members": [
        {
            "id": "member1@contoso.com",
            "principalType": "Person"
        },
        {
            "id": "member2@contoso.com",
            "principalType": "Person" 
        },
        {
            "id": "member3@contoso.com",
            "principalType": "Person"
        },
        {
            "id": "member4@contoso.com",
            "principalType": "Person"
        }
    ],
    "hasLeaderOnlySectionGroup": true
}

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

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, staff notebooks also have the following properties:
  • memberSections. The member sections in the notebooks.
  • leaders. The leaders that can access the notebook.
  • member. The members that can access the notebook.
  • hasLeaderOnlySectionGroup. true if the notebook contains a Leader 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 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.

{
    "hasLeaderOnlySectionGroup": true
}
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.

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

{
    "hasLeaderOnlySectionGroup": true
}

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

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 staff notebooks

To get one or more staff notebooks, send a GET request to the staffNotebooks 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.

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.

GET ../v1.0/users/{leader-id}/notes/staffNotebooks?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 /staffNotebooks 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 staff notebooks in JSON format.

In addition to regular notebook properties, staff notebooks also have the following properties:
  • memberSections. The member sections in the notebooks.
  • leaders. The leaders that can access the notebook.
  • member. The members that can access the notebook.
  • hasLeaderOnlySectionGroup. true if the notebook contains a Leader 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 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.

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

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

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 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.

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

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.

POST ../v1.0/users/{leader-id}/notes/staffNotebooks/{notebook-id}/leaders 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

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

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

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 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.

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.

DELETE ../v1.0/users/{leader-id}/notes/staffNotebooks/{notebook-id}/members/{member-id} 
Authorization: Bearer {token}
Accept: application/json

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

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 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.

{
    "sectionIds": [
        "section1-id", 
        "section2-id",
        ...
    ]
}
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.

Example

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

POST ../v1.0/me/notes/staffNotebooks/{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.

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.

See also