API Home >> Sheet >> API Reference >> books

Get a list of workbooks for the user in his Zoho Sheet account.

Request URL : 

                                XML : http://sheet.zoho.com/api/private/xml/books?apikey=[API Key]&ticket=[Ticket]

                                JSON : http://sheet.zoho.com/api/private/json/books?apikey=[API Key]&ticket=[Ticket]

Request parameters

Field	Description
start-from [optional]	[integer] - Sets the initial workbook number from which the workbooks will be listed. If there are 10 workbooks and start-from value is set to 3, then the workbooks will be listed from the 3rd workbook.
limit [optional]	[integer] - Sets the number of workbooks to be listed. If the limit value is set to 5 then the number of workbooks listed is 5.
order-by [optional]	[string - (createdTime | lastModifiedTime | name)] - Order workbooks by createdTime, lastModifiedTime & workbook name.
sort-order [optional]	[string - (asc | desc)] - Arrange the workbooks in ascending or descending order. Default sorting is done in descending order.

Response fields

The schema document for the API response is located at: http://sheet.zoho.com/schema/books.xsd

Field	Description
workbookId	Unique ID associated with each workbook in the list.
workbookName	Name of one of the workbooks that is being listed.
createdTime	Number of milliseconds between the workbook created time and midnight, January 1, 1970 UTC.
lastModifiedTime	Number of milliseconds between the last modified time and midnight, January 1, 1970 UTC.
lastModifiedBy	Specifies the Email ID of the person who has last edited the workbook. In case the workbook is shared & it is edited by one of the invitees, then the Email ID will be different from that of the author_name's ID.
lockedBy	Checks whether the workbook has been locked exclusively for editing in a shared environment by a user.
updateLock	Ensures that updates made to workbook are consistent when concurrent edit requests are sent to the same workbook.

Sample Response

The following is the sample response for the above method:

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/private/xml/books">
  <result>
    <workbooks>
      <workbook>
        <workbookId>6000000004003</workbookId>
        <workbookName>Expenses</workbookName>
        <createdTime>1172137033182</createdTime>
        <lastModifiedTime>1180593219644</lastModifiedTime>
        <lastModifiedBy>tt2</lastModifiedBy>
        <lockedBy />
        <updateLock>1180593219644</updateLock>
      </workbook>
      <workbook>
        <workbookId>6000000002011</workbookId>
        <workbookName>RGB Converter</workbookName>
        <createdTime>1174374756812</createdTime>
        <lastModifiedTime>1175593219644</lastModifiedTime>
        <lastModifiedBy>tt2</lastModifiedBy>
        <lockedBy />
        <updateLock>1175593219644</updateLock>
      </workbook>
    </workbooks>
  </result>
</response>

Equivalent JSON response

{
  "response":
   {
        "uri": "/api/private/json/books",
        "result":
        {
           "workbooks":
            {
                "workbook":
                [
                    {
                        "workbookId":"6000000004003",
                        "workbookName":"Expenses",
                        "createdTime":1172137033182,
                        "lastModifiedTime":1180593219644,
                        "lastModifiedBy":"tt2",
                        "lockedBy":"",
                        "updateLock":"1180593219644"
                     },
                     {
                        "workbookId":"6000000002011",
                        "workbookName":"RGB Converter",
                        "createdTime":1174374756812,
                        "lastModifiedTime":1175593219644,
                        "lastModifiedBy":"tt2",
                        "lockedBy":"",
                        "updateLock":"1175593219644"
                     }
                ]
            }
         }
    }
}  

Errors

Displaying list of workbooks method may return general & input errors.