Evernote Business

Interacting with the Evernote Business API

---

Evernote Business provides businesses with the means to collect, organize and share company information. We do this using many of the same tools that exist in Evernote, which provides a consistent and familiar experience for our users. If you're not sure what Evernote Business is exactly, visit the product page for a more thorough overview.

The only real prerequisite for working with the Evernote Business API is familiarity with the Evernote Cloud API, particularly the notebook sharing facilities. Most of the functions used to access Evernote Business data are very similar to—in many cases, exactly the same as—their equivalents found in the Evernote Cloud API.

There are, of course, a number of functions and techniques unique to the Evernote Business API. We'll talk about them in a second, but first we need to describe how Evernote Business data is stored and accessed.

Understanding the Evernote Business data model

When an Evernote user joins a business, they're essentially creating a second Evernote account using the same login. Data stored in the user's personal Evernote account and Evernote Business data are stored in physically different places (shards) and are owned by different entities. When a non-business user adds data to their account, they're free to do whatever they like with said data, including permanently deleting it. For a business user, it's analogous to linking someone else's notebook to her account: she doesn't own the business notebook and can't delete it (though, she can leave it). If she creates a note in the business notebook, she can move it to the Trash, but can't permanently delete it. Deleting notes and notebooks are capabilities reserved for the owner of the information. For Evernote Business, the owner of the information is the business itself.

So, to reiterate, here are the main differences (as far as data permissions and storage) between Evernote and Evernote Business:

• Users of Evernote Business do not retain ownership of data they add to business notebooks. Business notes and notebooks are the property of the business, not the user who created them.
• Business data is usually stored on a different shard (physical server) than personal data.
• Business data is always accessed through a Business NoteStore instance.

Determining if a user is part of a business

A valid Evernote account doesn't necessarily mean that the account holder is part of a business. To determine whether a given user is associated with a business, we can query the user's User instance for the businessId member in the User's instance of Accounting. You can get the User instance by calling UserStore.getUser (which requires a valid OAuth token or developer token):

Authenticating to a business

Once your application has authenticated to the User's Evernote account (your application has an authentication token obtained via OAuth or a developer token, in other words) and you have determined that the user is part of a business, call UserStore.authenticateToBusiness to authenticate your application to their associated business, passing the token as the single parameter. If an exception isn't thrown, then the user has been successfully authenticated:

Using the return value in the above example, we can access details about the business using the AuthenticationResult instance. See the type definition for all available attributes.

For the current discussion, we're most concerned with the value of AuthenticationResult.authenticationToken, which we'll use to make all subsequent API calls dealing with the user's Evernote Business account.

Creating a Business NoteStore instance

After authenticating to a business, you're probably going to want to view notebooks, create notes, etc. using the NoteStore. The Business API uses the same NoteStore type used by normal Evernote API clients and is instantiated the same way: using the noteStoreUrl value associated with the user. You can retrieve this value by querying the noteStoreUrl property of the AuthenticationResult returned by UserStore.authenticateToBusiness.

Once we have the NoteStore URL, we use that to create our instance of NoteStore and start making API calls:

Listing all user-accessible notebooks in a business

Using your instance of NoteStore that's associated with the user (not the business), you can call NoteStore.listLinkedNotebooks to see a list of all of the business notebooks the user has linked to their account:

Here, we simply request all of the linked notebooks associated with the user and check for the presence of a businessId member — if it's present, the notebook is a business notebook.

Creating a business notebook

Creating a new notebook in a business (a business notebook) is almost the same as creating a notebook in a user's personal account. Simply create an instance of Notebook and call NoteStore.createNotebook to create the notebook. Unlike a personal notebook, creating a business notebook involves the automatic creation of a SharedNotebook that grants the creator full access to the new notebook. The newly created business notebook doesn't belong to our user - it belongs to the business - but they have been given access to create, update and remove notes in the notebook, and to share the notebook with other users.

Unlike creating personal notebooks, there's a second step involved in creating a new business notebook. Our application must create a new LinkedNotebook that binds the business notebook to the user's personal account. First, we need to grab the instance of SharedNotebook that describes the current user's ability to access and modify the notebook. We do this by grabbing the first element in the notebook's sharedNotebooks collection. Then, using the shareKey value from the SharedNotebook instance (as well as the username and shard of the owner and the notebook's name), we create and populate an instance of LinkedNotebook and link it to the current user's account by calling NoteStore.createLinkedNotebook. Note that this call takes the OAuth token, not the token associated with the user's business account, and uses the normal NoteStore client, not the business NoteStore.

Here's a simple example of the process of creating a Business notebook and immediately linking it to the creator's account:

Assuming the wheels didn't fall off, the Business notebook in question will now be visible in the user's notebook list in the Evernote client applications.

Creating notes in a business notebook

To create a note in a business notebook, you'll need to complete this short list of steps:

1. Locate the LinkedNotebook instance that connects the business notebook with the user's account.
2. Use the shareKey property of the LinkedNotebook in conjunction with user's authentication token to call NoteStore.authenticateToSharedNotebook. This API function will return an instance of AuthenticationResult containing a new authenticationToken that will only be used for interacting with the SharedNotebook in question.
3. Retrieve the associated SharedNotebook instance by calling getSharedNotebookByAuth and passing the new authentication token (from the previous step) as the single parameter.
4. Using the notebookGuid value from the SharedNotebook instance, you can now call createNote against the business NoteStore, passing the business authentication token, which we defined earlier.

Need help?

If you have trouble implementing the Evernote Business API and would like assistance, head over to the developer support page.