Create Session

Use this API to create a new workbook session.

Excel APIs can be called in one of two modes:

  1. Persistent session - All changes made to the workbook are persisted (saved). This is the usual mode of operation.
  2. Non-persistent session - Changes made by the API are not saved to the source location. Instead, the Excel backend server keeps a temporary copy of the file that reflects the changes made during that particular API session. When the Excel session expires, the changes are lost. This mode is useful for apps that need to do analysis or obtain the results of a calculation or a chart image, but not affect the document state.

To represent the session in the API, use the workbook-session-id: {session-id} header.

Note: The session header is not required for an Excel API to work. However, we recommend that you use the session header to improve performance. If you don't use a session header, changes made during the API call are persisted to the file.

Error Handling

This request might occasionally receive a 504 HTTP error. The appropriate response to this error is to repeat the request.


One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Files.ReadWrite
Delegated (personal Microsoft account) Not supported.
Application Not supported.

HTTP request

POST /workbook/createSession

Request headers

Name Description
Authorization Bearer {token}. Required.

Request body

In the request body, supply a JSON representation of WorkbookSessionInfo object.


If successful, this method returns 201 Created response code and WorkbookSessionInfo object in the response body.



Here is an example of the request.

Content-type: application/json
Content-length: 52

  "persistChanges": true

In the request body, supply a JSON representation of WorkbookSessionInfo object.


Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 201 Created
Content-type: application/json
Content-length: 52

  "id": "id-value",
  "persistChanges": true

SDK sample code

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var persistChanges = true;

await graphClient.Me.Drive.Items["{id}"].Workbook

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.