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
Creating and activating a business on sandbox
To use the business API on our sandbox server, you'll need to create a test business by following the steps below
- Visit the business account creation page on sandbox.
- Create your business account by selecting Annual invoice as a payment method.
- Open a ticket to request the business activation.
Note that, while Evernote Business is a paid product, there is no charge to create or activate an Evernote Business account on sandbox. But, keep in mind that sandbox is for testing and development only.
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.
Note: Authentication tokens issued by
UserStore.authenticateToBusiness are only valid for one hour (as opposed to OAuth tokens, which are good for a full year). This means that your app will frequently need to re-authenticate with Evernote Business using the longer-lived OAuth token. Since the business authentication tokens are so short-lived, it's very probable that your app will encounter
EDAMUserException with the
AUTH_EXPIRED error code when trying to call a business API; ensure that your code accounts for this condition.
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
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
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:
- Locate the
LinkedNotebookinstance that connects the business notebook with the user's account.
- Use the
shareKeyproperty of the
LinkedNotebookin conjunction with user's authentication token to call
NoteStore.authenticateToSharedNotebook. This API function will return an instance of
AuthenticationResultcontaining a new
authenticationTokenthat will only be used for interacting with the
- Retrieve the associated
SharedNotebookinstance by calling
getSharedNotebookByAuthand passing the new authentication token (from the previous step) as the single parameter.
- Using the
notebookGuidvalue from the
SharedNotebookinstance, you can now call
createNoteagainst the business
NoteStore, passing the business authentication token, which we defined earlier.
If you'd like to see a working sample application that demonstrates most of the basic Evernote Business API functionality, you can view our sample application on Github.
If you have trouble implementing the Evernote Business API and would like assistance, head over to the developer support page.