Use note tags with the OneNote API

Use the data-tag attribute to add and update check boxes, stars, and other note tags on a OneNote page.

Last modified: January 22, 2016

Applies to: OneNote service

In this article
Add or update note tags on OneNote pages
Note tags in the output HTML of a OneNote page
Built-in note tags for OneNote
Additional resources

Note Note

See this topic on our new documentation site for consumer and enterprise OneNote APIs.

In OneNote, note tags display an icon or highlight. The following image shows three note tags in a OneNote page.


Three note tags displayed on a OneNote page

In the HTML of a OneNote page, a note tag is represented by the data-tag attribute. For example:

    An unchecked to-do box:  <p data-tag="to-do">

    A checked to-do box:  <p data-tag="to-do:completed">

    A star:  <h2 data-tag="important">

The data-tag value is composed of the shape and status properties:

    data-tag=$shape[:$status]

Property

Description

shape

The identifier of the note tag (example: to-do or important).

status

The status of check-box note tags. This is used only to set check boxes as completed.

You can use data-tag to add, change, and remove built-in note tags when you create or update pages. They're returned in the page HTML, so you can consume them too.

Note Note

OneNote note tags are not searchable with the OneNote API, but you can use the $search query string option for full-text search of OneNote content. Learn more about search.

In the page HTML, note tags are represented by the compound data-tag attribute. To add or update a built-in note tag, just use the data-tag attribute in the target element. For example, here's a paragraph marked as important:

    <p data-tag="important">...</p>

Multiple note tags are comma delimited:

    <p data-tag="important, critical">...</p>

You can define the data-tag attribute on the following elements:

  • p

  • ul, ol, li (see more about lists)

  • img

  • h1 - h6

  • title

See Built-in note tags for OneNote for a list of note tags that you can use with the OneNote API.

Note Note

Adding or updating custom tags using the OneNote API is not supported.

Examples

Here's a simple to-do list with the first item completed.

<p data-tag="to-do:completed" data-id="prep">Till garden bed</p> 
<p data-tag="to-do" data-id="spring">Plant peas and spinach</p>
<p data-tag="to-do" data-id="summer">Plant tomatoes and peppers</p>

Note that the <p> tags above each include a data-id attribute. This makes it easier to update the check-box note tags. For example, the following request marks the spring planting to-do item as completed.

PATCH https://www.onenote.com/api/v1.0/me/notes/pages/{page-id}/content

Content-Type: application/json
Authorization: Bearer {token}

[
   {
    'target':'#spring',
    'action':'replace',
    'content':'<p data-tag="to-do:completed"  data-id="spring">Plant peas and spinach</p>'
  }
]

The following request creates a page that contains all built-in note tags.

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

Content-Type: text/html
Authorization: Bearer {token}


<!DOCTYPE html>
<html>
  <head>
    <title data-tag="to-do:completed">All built-in note tags</title>
  </head>
  <body>
    <h1 data-tag="important">Paragraphs with built-in note tags</h1>
    <p data-tag="to-do">to-do</p>
    <p data-tag="important">important</p>
    <p data-tag="question">question</p>
    <p data-tag="definition">definition</p>
    <p data-tag="highlight">highlight</p>
    <p data-tag="contact">contact</p>
    <p data-tag="address">address</p>
    <p data-tag="phone-number">phone-number</p>
    <p data-tag="web-site-to-visit">web-site-to-visit</p>
    <p data-tag="idea">idea</p>
    <p data-tag="password">password</p>
    <p data-tag="critical">critical</p>
    <p data-tag="project-a">project-a</p>
    <p data-tag="project-b">project-b</p>
    <p data-tag="remember-for-later">remember-for-later</p>
    <p data-tag="movie-to-see">movie-to-see</p>
    <p data-tag="book-to-read">book-to-read</p>
    <p data-tag="music-to-listen-to">music-to-listen-to</p>
    <p data-tag="source-for-article">source-for-article</p>
    <p data-tag="remember-for-blog">remember-for-blog</p>
    <p data-tag="discuss-with-person-a">discuss-with-person-a</p>
    <p data-tag="discuss-with-person-b">discuss-with-person-b</p>
    <p data-tag="discuss-with-manager">discuss-with-manager</p>
    <p data-tag="send-in-email">send-in-email</p>
    <p data-tag="schedule-meeting">schedule-meeting</p>
    <p data-tag="call-back">call-back</p>
    <p data-tag="to-do-priority-1">to-do-priority-1</p>
    <p data-tag="to-do-priority-2">to-do-priority-2</p>
    <p data-tag="client-request">client-request</p>
    <h1 data-tag="important">Paragraphs with check boxes marked with "completed" status</h1>
    <p data-tag="to-do:completed">to-do:completed</p>
    <p data-tag="discuss-with-person-a:completed">discuss-with-person-a:completed</p>
    <p data-tag="discuss-with-person-b:completed">discuss-with-person-b:completed</p>
    <p data-tag="discuss-with-manager:completed">discuss-with-manager:completed</p>
    <p data-tag="schedule-meeting:completed">schedule-meeting:completed</p>
    <p data-tag="call-back:completed">call-back:completed</p>
    <p data-tag="to-do-priority-1:completed">to-do-priority-1:completed</p>
    <p data-tag="to-do-priority-2:completed">to-do-priority-2:completed</p>
    <p data-tag="client-request:completed">client-request:completed</p>
    <h1 data-tag="important">Multiple note tags</h1>
    <p data-tag="project-a,  client-request:completed">Two note tags:  project-a, client-request:completed</p>
    <p data-tag="idea, send-in-email, question">Three note tags:  idea, send-in-email, question</p>
    <h1 data-tag="important">Using note tags with other elements</h1>
    <p><b>Note tag on a list item:</b></p>
    <ul>
      <li data-tag="to-do-priority-1:completed">Make a to-do list</li>
    </ul>
    <p><b>Note tag on an image:</b></p>
    <img data-tag="source-for-article" src="http://placecorgi.com/200" />
    <p><b>Note tag with embedded style:</b></p>
    <p data-tag="important">Next time, <b>don't</b> forget to invite <span style="background-color:yellow">Dan</span>.</p>
  </body>
</html>

For more information about creating pages, see POST Pages and Make simple captures. For more about updating pages, see PATCH pages and Update page content.

Note tags on lists

Here are some guidelines for working with note tags on lists:

  • Use p elements for to-do lists. They don't display a bullet or number, and they're easier to update.

  • To create or update ul or ol elements that display the same note tag for all list items:

      Define data-tag on the ul or ol. To update the entire list, you'll need to redefine data-tag on the ul or ol.

  • To create or update ul or ol elements that display unique note tags for list items:

      Define data-tag on the li elements, and don’t nest the li elements in a ul or ol. To update the entire list, you'll need to replace the ul that's returned in the output HTML with the unnested li elements.

  • To update specific li elements:

      Address them individually and define the data-tag on the li element. Any individually addressed li element can display a unique note tag, even if the list was originally created with the same note tags.

    For example, the following JSON change object updates the second item in the first list below.

    [
       {
        'target':'{target-id}',
        'action':'replace',
        'content':'<li data-tag="project-b">Now this item has a Project B note tag</li>'
      }
    ]
    

    See Update page content to learn how to get target IDs and make update requests.

These guidelines are based on the following rules that the OneNote API applies:

  • The data-tag setting for a ul or ol overrides all settings on child li elements. This applies even when the ul or ol doesn't specify a data-tag but its child li elements do.

    For example, if you create a ul or ol that defines data-tag="project-a", all its list items will display the Project A note tag, and all data-tag settings move to the list-item level (see example below). And if the ul or ol doesn’t define a data-tag, none of its items will display a note tag, regardless of any explicit settings on child li elements.

  • In output HTML, the data-tag setting for a li is defined on a nested span element (see example below).

  • Unique data-tag settings are honored for list items under the following conditions:

    • The li elements are not nested in a ul or ol in a create or update request (see example below).

    • An li element is individually addressed in an update request.

  • Unnested li elements sent in input HTML are returned in a ul in the output HTML (see example below).

The following code shows how some of these rules are applied. The input HTML creates two lists with note tags. The output HTML is what's returned for the lists when you retrieve page content. (Learn more about input and output HTML.)

Input HTML

<!--To display the same note tag on all list items, define note tags on the ul or ol.--> 
<ul data-tag="project-a" data-id="agenda">
  <li>This item has a Project A note tag</li>
  <li>This item has a Project A note tag, too</li>
</ul>

<!--To display unique note tags on list items, don't nest li elements in a ul or ol.--> 
<li data-tag="idea" data-id="my-idea">This item has an Idea note tag</li>
<li data-tag="question" data-id="my-question">This item has a Question note tag</li>

Output HTML

<ul>
  <li><span data-tag="project-a">This item has a Project A note tag</span></li>
  <li><span data-tag="project-a">This item has a Project A note tag, too</span></li>
</ul>
<br />
<ul>
  <li style="..."><span data-tag="idea">This item has an Idea note tag</span></li>
  <li style="..."><span data-tag="question">This item has a Question note tag</span></li>
</ul>

Built-in note tags are included in the output HTML when you retrieve page content by sending a GET request to the content endpoint:

  GET ../api/v1.0/pages/{page-id}/content

The data-tag attribute in the output HTML always includes the shape value, and it only includes status if it represents a check-box note tag that's set to completed. The following examples show the input HTML used to create some note tags and the output HTML that's returned.

Input HTML

<h1>Status meeting</h1>
<p data-tag="important">Next week's meeting has been moved to <b>Wednesday</b>.</p>
<p data-tag="question">What are the exact dates for the conference?</p>
<p>Upcoming training opportunities. See Katie for more info.</p>
<p data-tag="project-a">Around the room updates.</p>
<ul data-tag="critical">
  <li>Design handouts</li>
  <li>Plan keynote</li>
</ul>

Output HTML

<h1 style="...">Status meeting</h1>
<p data-tag="important">Next week's meeting has been moved to <span style="font-weight:bold">Wednesday</span>.</p>
<p data-tag="question">What are the exact dates for the conference?</p>
<p>Upcoming training opportunities. See Katie for more info.</p>
<p data-tag="project-a">Around the room updates.</p>
<ul>
  <li><span data-tag="critical">Design handouts</span></li>
  <li><span data-tag="critical">Plan keynote</span></li>
</ul>

Note that the data-tag attribute defined at the list level is pushed to its list items. For more information about using note tags with lists, see Note tags on lists.

NoteNote

In the output HTML, the definition and remember-for-later note tags are both returned as data-tag="remember-for-later". The title element doesn't return any note tag information.

OneNote includes the following built-in note tags:

Built-in note tags

Built-in note tags

The values you can assign to the data-tag attribute are shown below.

shape[:status]

to-do

to-do:completed

important

question

definition

highlight

contact

address

phone-number

web-site-to-visit

idea

password

critical

project-a

project-b

remember-for-later

movie-to-see

book-to-read

music-to-listen-to

source-for-article

remember-for-blog

discuss-with-person-a

discuss-with-person-a:completed

discuss-with-person-b

discuss-with-person-b:completed

discuss-with-manager

discuss-with-manager:completed

send-in-email

schedule-meeting

schedule-meeting:completed

call-back

call-back:completed

to-do-priority-1

to-do-priority-1:completed

to-do-priority-2

to-do-priority-2:completed

client-request

client-request:completed

Show: