API References

Zoho Docs API

The Zoho Docs API provides partners and organizations with a more tightly integrated means of interacting with Zoho's applications for secure storage and document management infrastructure.

Zoho Docs API can be integrated into an existing document system extending the range of functionality. Partners can build their own applications and leverage the collaboration and document sharing capabilities of the integrated Zoho services. The Zoho Docs APIs also provides a means for document storage so that partners can focus on their core applications and services rather than build and manage a storage solution.

Authorize Request

Authentication Token

To use Zoho Docs API's, you will require Zoho Docs Authentication Token from Zoho Accounts. Please make sure that you have access to retrieve or extract the data from Zoho Docs API service.

Generate AuthToken

To generate AuthToken, you need to send an request to Zoho Accounts as described below. AuthToken can be generated in two ways:

  • API Mode
  • Browser Mode

API Mode

Description Generates the AuthToken.
URL Structure https://accounts.zoho.com/apiauthtoken/nb/create
Method POST
Parameters
ParameterValueDescription
SCOPE string - (ZohoPC/docsapi) Mandatory. Specify the value as ZohoPC/docsapi
EMAIL_ID string Mandatory. Specify your Zoho Docs User name or Email Id
PASSWORD string Mandatory. Specify your Zoho Docs password
DISPLAY_NAME string - (ZOHODOCS) Mandatory. Specify your user app name
Returns Returns the generated AuthToken for the specified user.

Browser Mode

Description Generates the AuthToken.
URL Structure https://accounts.zoho.com/apiauthtoken/create
Method GET
Parameters
ParameterValueDescription
SCOPE string - (ZohoPC/docsapi) Mandatory. Specify the value as ZohoPC/docsapi
DISPLAY_NAME string - (ZOHODOCS) Mandatory. Specify your user app name
Returns Returns the generated AuthToken for the specified user.

Sample Response for AuthToken

#
#Tue Aug 27 16:26:02 IST 2013
AUTHTOKEN=f46973ff35f9778a940a89fa7a48cd7f
RESULT=TRUE

Manage AuthToken

You can view, delete and regenerate the Auth Token generated for your account from the 'My Zoho Account' Page.
 
  1. Log into Zoho Docs
  2. Open [Username] > My Zoho Account
  3. In the My Zoho Account page, click Settings > Active Authtokens

In this page, you can also Remove or Regenerate Auth Tokens.

Note:

  • Removing an Auth Token will delete the token permanently.
  • If you regenerate Auth Token, update your program with the new token.
 

Upload Files

/upload

Description Uploads a file using POST semantics.
URL Structure https://apidocs.zoho.com/files/v1/upload?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
filename string Mandatory. Name of the file to be uploaded
fid string Optional. id of the folder where files to be uploaded to a folder
wsid string Optional. id of the workspace where files to be uploaded to a workspace
content string Mandatory. Actual document content to be uploaded
Returns Returns the meta data of the uploaded document
Errors 404 User is not valid
9837 Missing Content
Notes This API supports maximum file size limit of 100 MB for free users and 500 MB for paid users.

Sample Response for upload

{
    "response":
        [
            {"uri":"/files/v1/upload"},
            {"message":"UPLOAD_SUCCESS"},
            {"result":
                [
                {"documentname":"Tulips.jpg"},
                {"uploaddocid":"3yprga7361deb32524816b36e72f27baa02c9"}
                ]
            }
       ]
}

Download Files

/download

Description Downloads a file.
URL Structure https://apidocs.zoho.com/files/v1/content/<DOC_ID>?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
docversion string Optional. Version of the document to be downloaded. This defaults to recent one.
Returns The specified file's content with the requested version.
Errors 9832 The file wasn't found for the given doc id.

Manage File Metadata

/create

Description Creates a new document or file
URL Structure https://apidocs.zoho.com/files/v1/create?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
filename string Mandatory. Name of the file to be created
service string - (document | spreadsheet | presentation) Mandatory. Any of the given service
type string - (doc | template) Mandatory. Specify the type to create a template or document
parentfolderid string Optional. Id of the folder in which document to be created. This takes default as root folder.
Returns Returns the success message
Errors 404 User is not valid
9822 Not a valid service type specified
9823 Error while creating a document

/files

Description Retrieves the user's files
URL Structure https://apidocs.zoho.com/files/v1/files?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
category string - (documents | spreadsheets | presentations | pictures | music | videos | sharedbyme | sharedtome | thrashed) Optional. List of files based on category
start integer Optional. This value is set to get the list of files from that entry
limit integer Optional. This value is set to get the files list limit. If the both start and limit is not set, default value 0 and 200 will be taken respectively.
Returns Specified category files.
Errors 404 User is not valid
9830 The start parameter was not set correctly
9831 The limit parameter was not set correctly
Notes This API also support the range to allow retrieving the partial file list.

Sample Response for files

{
        "FILES": [
            {
                "AUTHOR":"Tom Hill",
                "AUTHOR_EMAIL":"tomhill@yahoo.com",
                "LAST_MODIFIEDTIME_IN_MILLISECONDS":1371015460774,
                "SCOPE":0,
                "FILE_EXTN":"jpg",
                "DOCID":"8tw2gf0022bc32fb94c4990f40658dd091983",
                "DOCNAME":"Chrysanthemum.jpg",
                "FOLDER_ID":"folder",
                "LAST_MODIFIEDTIME":"Jun 11",
                "SERVICE_TYPE":"upload",
                "IS_LOCKED":false,
                "FILETYPE":"image"
            }
        ]
    }

/copy

Description Copies a file or document to a new location
URL Structure https://apidocs.zoho.com/files/v1/copy?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to be copied
folderid string Mandatory. Id of folder to copy the new file
Returns Returns the Success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.

Sample Response for copy

{
    "response":
          {
           "result":
                  {"message":"DOCUMENT_COPIED_SUCCESSFULLY"},
                   "uri":"/files/v1/move"
          }
}

/move

Description Moves a file or document to a specified location
URL Structure https://apidocs.zoho.com/files/v1/move?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to be moved
folderid string Mandatory. Id of folder to copy the new file
Returns Returns the Success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.

Sample Response for move

{

    "response":
          {
           "result":
                  {"message":"DOCUMENT_MOVED_SUCCESSFULLY"},
                   "uri":"/files/v1/move"
          }
}

/trash

Description Moves the file to trash.
URL Structure https://apidocs.zoho.com/files/v1/trash?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to be trashed
Returns Returns the success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.

Sample Response for trash

{
    "response":
          {
           "result":
                  {"message":"DOCUMENT_TRASHED_SUCCESSFULLY"},
                   "uri":"/files/v1/move"
          }
}

/restore

Description Restores the file which has been trashed
URL Structure https://apidocs.zoho.com/files/v1/restore?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to be restored
Returns Returns the success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.

Sample Response for Restore

{
    "response":
          {
           "result":
                  {"message":"DOCUMENT_RESTORED_SUCCESSFULLY"},
                   "uri":"/files/v1/move"
          }
}

/delete

Description Files will be removed from user's account
URL Structure https://apidocs.zoho.com/files/v1/delete?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to be deleted
Returns Returns the success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.

Sample Response for Delete

{
    "response":
          {
           "result":
                  {"message":"DOCUMENT_DELETED_SUCCESSFULLY"},
                   "uri":"/files/v1/move"
          }
}

/rename

Description Renames the existing file or document
URL Structure https://apidocs.zoho.com/files/v1/rename?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to be renamed
docname string Mandatory. New name for the document or file
Returns Returns the success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.

Sample Response for Rename

{
       "response":
           {"result":
                    {"DocumentDetails":
                            {"DocumentDetail":
                                    {
                                        "message":"DOCUMENT_RENAMED_SUCCESSFULLY",
                                        "DOCUMENT_NAME":"chumma.png",
                                        "DOCID":"3yprg69b889a4c0634f77986f948a38ce8b1c"
                                    }
                            }   
                    }
            ,"uri":"/files/v1/rename"
            }
     }

Share Files

/share

Description Shares a file to a private email id's
URL Structure https://apidocs.zoho.com/files/v1/share?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docids string Mandatory. Id of the document or file to be shared
emailids string Mandatory. mail id of the users to share
permission string - (readonly|readwrite|coowner) Mandatory. file shared to the user with the specified permission
notify boolean - (true|false) Optional. notifies the shared user when file or document is shared via mail
message string Optional. message to the shared user via mail
Returns Returns the success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.
9839 The given email id's is not valid

Sample Response for Share

{
    response:
    [
        {
            uri: "/files/v1/share"
        },
        {
            message: "SHARED_DOCUMENT_SUCCESS"
        },
        {
            result:
            [
                {
                    shareduserlist: "calvin@gmail.com,xylan@gmail.com,"
                },
                {
                    sharedgroupslist: "2345234,343424,3483439,143840,"
                }
            ]
        }
    ]
}

/visibility

Description Sharing a file via link
URL Structure https://apidocs.zoho.com/files/v1/share/visibility?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to be shared via link
visibility string - (orglinkshare | orgshare | linkshare | private ) Mandatory. To change the document visibility.
permission string - (readonly|readwrite) Mandatory. file shared to the user with the specified permission
password string Optional. password required if the doc is shared via link share with secured
expireson date - (mm/dd/yyyy) Optional. specify the date till the document can be shared via link share
Returns Returns the success message with the generated link
Errors 404 User is not Valid
9832 The file wasn't found for the given docid.
9834 The visibility parameter is not valid

Sample Response for visibility

{
    response:
    [
        {
            uri: "/files/v1/share/visibility"
        },
        {
            message: "CHANGE_VISIBILITY_SUCCESS"
        },
        {
            result:
            [
                {
                 permaLink:"https://docs.zoho.com/file/i5fa1a0081eed629b4f978aae3a6ab296790a"
                }
            ]
        }
    ]
}

/update

Description Updates the permission of existing shared file
URL Structure https://apidocs.zoho.com/files/v1/share/update?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to updated document visibility
visibility string - (orglinkshare | orgshare | linkshare | private ) Mandatory. To change the document visibility.
permission string - (readonly|readwrite) Mandatory. file shared to the user with the specified permission
emailids string Optional. mail id of the users to share (Mandatory if the visibility is set as private).
Returns Returns the success message.
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.
9839 The given email id's is not valid
9834 The visibility parameter is not valid

Sample Response for update

{
    response:
    [
        {
            uri: "/files/v1/share/update"
        },
        {
            message: "UPDATE_SHARE_SUCCESS"
        },
        {
            result:
            [
                {
                    documentid: "i5fa1a0081eed629b4f978aae3a6ab296790a"
                }
            ]
        }
    ]
}

/remove

Description Removes the share permission for the shared user
URL Structure https://apidocs.zoho.com/files/v1/share/remove?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to remove share
emailids string Mandatory. mail id of the users to share
Returns Returns the success message
Errors 404 User is not valid
9832 The file wasn't found for the given doc id.
9839 The given email id's is not valid

Sample Response for remove

{
    response:
    [
        {
            uri: "/files/v1/share/remove"
        },
        {
            message: "UNSHARED_DOCUMENT_SUCCESS"
        },
        {
            result:
            [
                {
                    documentid: "i5fa1a0081eed629b4f978aae3a6ab296790a"
                }
            ]
        }
    ]
}

/details

Description Returns the shared details of a document or file
URL Structure https://apidocs.zoho.com/files/v1/share/details?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document or file to get shared details
Returns Returns the share details
Errors 9832 The file wasn't found for the given doc id.
404 User is not valid

Sample Response for share details

{
    "response":{
        "result":{
            "ReadOnly":{
                "sharedGroups":"",
                "sharedUserZuids":"",
                "sharedEmails":"",
                "sharedUsers":""
            },
            "coOwner":{
                "sharedUserZuids":"",
                "sharedEmails":"",
                "sharedUsers":""
            },
            "ReadWrite":{
                "sharedGroups":"332613,336474",
                "sharedUserZuids":"2324,17560",
                "sharedEmails":"",
                "sharedUsers":"tomhill@abc.com,jamesandy@biz.com"
            },
            "visibility":"orgshare",
            "permaLink":"https://docs.zoho.com/file/i5fa1a0081eed629b4f978aae3a6ab296790a"
        },
        "uri":"/files/v1/share/details"
    }
}

File Revisions

/revision

Description Revises the content of the existing file using POST semantics.
URL Structure https://apidocs.zoho.com/files/v1/revision?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document to be revision
filename string Mandatory. Name of the file to be revision.
content string Mandatory. content of the file to upload
Returns Returns the Success message
Errors 404 User is not valid
9837 Missing Content
Notes This API supports maximum file size limit of 100 MB for free users and 500 MB for paid users.

Sample Response for revision

{
    "response":
    [
        {"uri":"/files/v1/revision"},
        {"message":"Version Updated Successfully"},
        {"result":
                    [
                     {"documentname":"Tulips.jpg"},
                     {"uploaddocid":"3yprga7361deb32524816b36e72f27baa02c9"}
                    ]
        }
    ]
}

/details

Description Lists the revision details for the given document.
URL Structure https://apidocs.zoho.com/files/v1/revision/details?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document to be revision
type string - (owned|shared) Mandatory. specify which type of document.
Returns Returns the list of version details on success
Errors 404 User is not valid
9832 Document not found for given docId.

Sample Response for version details

{
    "DOCTYPE":"image",
    "FORMAT":"jpg",
    "DOCID":"3yprga7361deb32524816b36e72f27baa02c9",
    "DOCNAME":"Inventory stocks.jpg"
    "VERSION_INFO":
              [
                {
                 "VERSION":"2.0",
                 "DOCSIZE":"777 KB",
                 "DOCUPLOADTIME":"Aug 29 12:24 PM 2013"
               },
               {
                 "VERSION":"1.0",
                 "DOCSIZE":"620 KB",
                 "DOCUPLOADTIME":"Aug 28 10:59 AM 2013"
                }
              ]        
}

Folders

/folders

Description Returns the list of folders present in user's account
URL Structure https://apidocs.zoho.com/files/v1/folders?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
folderid string Optional. Id of the folder to get sub folder list. This takes default as root folder
Returns Returns the folders list
Errors 404 User is not valid

Sample Response for folder

[
    {"FOLDER_NAME":"My Folders","SUCCESS":"1"},   
    [
      {
       "FOLDER_ID":"3yprg626b688109df404da92acd6c5f1894a6",
       "PARENT_FOLDER_ID":"1",
       "FOLDER_NAME":"ABC"
      }
    ]
]

/create

Description Creates a new folder.
URL Structure https://apidocs.zoho.com/files/v1/folders/create?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
foldername string Mandatory. Name of the folder in which folder to be created.
parentfolderid string Optional. Id of the folder in which folder to be created. This takes default as root folder.
Returns Returns the newly created folder id
Errors 404 User is not valid

Sample Response for create folder

{
    "response":
        {
        "result":
            {"FolderDetails":
                    {"FolderDetail":
                        {
                         "message":"FOLDER_CREATED_SUCCESSFULLY",
                         "folder_name":"Projects",
                         "folder_id":"8tw2g62a6bc3d81da4c2c85646d679628aacb"
                        }
                    }
            }
            ,"uri":"/files/v1/folders/create"
        }
}

/rename

Description Renames the existing folder
URL Structure https://apidocs.zoho.com/files/v1/folders/rename?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Id of the folder to be renamed
foldername string Mandatory. New name for the folder
Returns Returns the success message
Errors 404 User is not valid

Sample Response for rename folder

{
    "response":
        {
         "result":
                 {"FolderDetails":
                     {"FolderDetail":   
                                 {"message":"FOLDER_RENAMED_SUCCESSFULLY",
                                  "folder_name":"testapi1",
                                   "folder_id":"8tw2g62a6bc3d81da4c2c85646d679628aacb"
                                  }
                       }
                  },
                  "uri":"/files/v1/folders/rename"
         }
}

/move

Description Moves the existing folder to specified location
URL Structure https://apidocs.zoho.com/files/v1/folders/move?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Id of the folder to be moved
destfolderid string Mandatory. Id of the folder to be moved
prevparentfolderid string Mandatory. Id of the folder in which current folder was present.
Returns Returns the success message
Errors 404 User is not valid

Sample Response for move folder

{
        "response":
            {
                "result":
                        {
                            "message":"FOLDER_MOVED_SUCCESSFULLY"
                        }
                ,"uri":"/files/v1/folders/move"
            }
    }

/copy

Description Copies the existing folder to a specified folder
URL Structure https://apidocs.zoho.com/files/v1/folders/copy?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Copies folder I.D
destfolderid string Mandatory. Specifies I.D of the destination folder (where existing folder copies).
Returns Returns the success message
Errors 404 User is not valid

Sample Response for copy folder

{"response":
            {"result":
                    {
                        "message":"COPY_FOLDER_SUCCESS",
                        "folderid":"3yprgba1a3aeccdfc44a1afc51e8aa3c99b26",
                        "status":"1"
                    },
                    "uri":"/files/v1/folders/copy"
            }
}

/trash

Description Folder will be moved to trashed
URL Structure https://apidocs.zoho.com/files/v1/folders/trash?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Id of the folder to be trashed
Returns Returns the success message
Errors 404 User is not valid

Sample Response for trash folder

{
        "response":
            {
                "result":
                        {
                            "message":"FOLDER_TRASHED_SUCCESSFULLY"
                        }
                ,"uri":"/files/v1/folders/move"
            }
    }

/restore

Description Restores the folder which has been trashed
URL Structure https://apidocs.zoho.com/files/v1/folders/restore?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Id of the folder to be restored
Returns Returns the success message
Errors 404 User is not valid

Sample Response for restore folder

{
        "response":
            {
                "result":
                        {
                            "message":"FOLDER_RESTORED_SUCCESSFULLY"
                        }
                ,"uri":"/files/v1/folders/move"
            }
    }

/delete

Description Deletes the folder from User's account
URL Structure https://apidocs.zoho.com/files/v1/folders/delete?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Id of the folder to be deleted
Returns Returns the success message
Errors 404 User is not valid

Sample Response for delete folder

{
        "response":
            {
                "result":
                        {
                            "message":"FOLDER_DELETED_SUCCESSFULLY"
                        }
                ,"uri":"/files/v1/folders/move"
            }
    }

/files

Description Retrieves the files and folders present in that folder
URL Structure https://apidocs.zoho.com/files/v1/folders/files?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
folderid string Optional. Id of the folder to retrieve the list. This takes default as my folder.
Returns Returns the list of files and folder
Errors 404 User is not valid

Sample Response for files in folder

{
    "FILES":      
        [
            {
             "FOLDER_ID":"cm31cdf8d437e1d89475490c8d78790c7478b",
             "AUTHOR_ID":"4145547",
             "LAST_MODIFIEDTIME_IN_MILLISECONDS":1369397398535,
             "SCOPE":0,
             "FILE_EXTN":"txt",
             "DOCID":"cm31c1882749ac9de48518691c0e48111c083",
             "LAST_MODIFIEDBY":"4145547",
             "LAST_MODIFIEDTIME":"May 24",
             "SERVICE_TYPE":"upload",
             "IS_LOCKED":false,
             "FILETYPE":"docs",
             "DOCNAME":"ids.txt"
            }
        ],
        "FOLDER":
            [
                {
                 "PARENTFOLDERID":"cm31cdf8d437e1d89475490c8d78790c7478b",
                 "FOLDERID":"z1g204cd6a2f5080f459b8659f8e24a1bd61e",
                 "FOLDERNAME":"test"
                }
            ]
}

Share Folders

/share

Description Share folders to private email I.Ds
URL Structure https://apidocs.zoho.com/files/v1/share?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderids string Mandatory. Specifies Folder I.D
emailids string Mandatory. Specifies email I.Ds of the users to be shared
permission string - (readonly|readwrite) Mandatory. Specifies the access permission for the shared folder.
notify boolean - (true|false) Optional. Notifies the shared user when a folder is shared via email
message string Optional. Message is sent to the shared user via email.
Returns Returns the success message
Errors 404 User is not valid.
9832 The folder was not found for the given folderid.
9839 The given emailids are not valid.

Sample Response for Share Folder

{"response":
            [
                {"uri":"/files/v1/share"},
                {"message":"SHARE_FOLDER_SUCCESS"},
                {"result":
                        [
                            {"shareduserlist":"aravind694,"}
                        ]
                }
            ]
}

/visibility

Description Sharing a folder via link
URL Structure https://apidocs.zoho.com/files/v1/share/visibility?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Folder I.D is shared through link.
visibility string - (orglinkshare | orgshare | linkshare | private ) Mandatory. Changes folder visibility
permission string - readonly Mandatory. Folder is shared to the user with the specified permission.
password string Optional. Password is required if the folder is shared via link and password protected.
expireson date - (mm/dd/yyyy) Optional. Specifies the date till the folder can be accessed via link.
Returns Returns the success message with the generated link
Errors 404 User is not Valid
9832 The folder was not found for the given folderid.
9834 The visibility parameter is not valid

Sample Response for Visibility

{"response":
            [
                {"uri":"/files/v1/share/visibility"},
                {"message":"CHANGE_VISIBILITY_SUCCESS"},
                {"result":
                            [
                                {"permaLink":"https://docs.zoho.com/folder/3yprgf644c24c4c7f43b79d852e02646109bd"}
                            ]
                }
            ]
}

/update

Description Updates the permission of existing shared folder
URL Structure https://apidocs.zoho.com/files/v1/share/update?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Specify folder I.D to change the existing permission/visibilty.
visibility string - (orglinkshare | orgshare | linkshare | private ) Mandatory. Changes the folder visibility
permission string - readonly Mandatory. Folder is shared to the user with the specified permission.(readwrite if visibility is set as private)
emailids string Optional. Share user email I.D. (Mandatory if the visibility is set as private).
Returns Returns the success message.
Errors 404 User is not Valid
9832 The folder was not found for the given folderid.
9839 The given emailids are not valid
9834 The visibility parameter is not valid

Sample Response for update

{"response":
            [
                {"uri":"/files/v1/share/update"},
                {"message":"UPDATE_SHARE_SUCCESS"},
                {"result":
                            [
                                {"folderid":"3yprgf644c24c4c7f43b79d852e02646109bd"}
                            ]
                }
            ]
}

/remove

Description Removes the share permission for the shared user
URL Structure https://apidocs.zoho.com/files/v1/share/remove?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
folderid string Mandatory. Specify folder I.Ds to remove sharing.
emailids string Mandatory. Share user email I.Ds.
Returns Returns the success message.
Errors 404 User is not Valid
9832 The folder was not found for the given folderid.
9839 The given emailids are not valid

Sample Response for Remove

{"response":
            [
                {"uri":"/files/v1/share/remove"},
                {"message":"UNSHARE_FOLDER_SUCCESS"},
                {"result":
                            [
                                {"folderid":"3yprgf644c24c4c7f43b79d852e02646109bd"}
                            ]
                }
            ]
}

/details

Description Returns the shared details of a folder
URL Structure https://apidocs.zoho.com/files/v1/share/details?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
folderid string Mandatory. Specify Folder I.D to get shared details.
Returns Returns the share details
Errors 9832 The folder was not found for the given folderid.
404 User is not Valid

Sample Response for Share Details

{
    "response":{
        "result":{
            "ReadOnly":{
                "sharedGroups":"",
                "sharedUserZuids":"1482406",
                "sharedEmails":"tomhill@abc.com",
                "sharedUsers":""
            },
            "coOwner":{
                "sharedUserZuids":"",
                "sharedEmails":"",
                "sharedUsers":""
            },
            "ReadWrite":{
                "sharedGroups":"",
                "sharedUserZuids":"",
                "sharedEmails":"",
                "sharedUsers":""
            },
            "visibility":"linkshare",
            "permaLink":"https://docs.zoho.com/folder/i5fa1a0081eed629b4f978aae3a6ab296790a"
        },
        "uri":"/files/v1/share/details"
    }
}

Tags

/tags

Description Returns the list of user tags
URL Structure https://apidocs.zoho.com/files/v1/tags?authtoken=AuthToken&scope=docsapi
Method GET
Returns Returns the list of user tags
Errors 404 User is not valid

Sample Response for tags

{
    "UserTagDetails":
            [
              {
               "tagName":"ABC",
               "tagId":"403347000000204019"
               }
            ]
}

/create

Description Creates a new user tag
URL Structure https://apidocs.zoho.com/files/v1/tags/create?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
tagname string Mandatory. Name of the tag to create.
Returns Returns the Tag Id
Errors 404 User is not valid

Sample Response for create tag

{
    "response":
           {
            "result":
                {"TagDetails":                       
                         {
                          "message":"TAG_ADDED_SUCCESSFULLY",
                          "tag_name":"Required for Project",
                          "tag_id":"403347000000261006"
                         }
                },
                "uri":"/files/v1/tags/create"
          }
}

/add

Description Adds a tag to a file or a document
URL Structure https://apidocs.zoho.com/files/v1/tags/add?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the file to which tag should be added
tagname string Mandatory. Name of the tag to be added.
Returns Returns the success message.
Errors 9832 The file wasn't found for the given doc id.
404 User is not valid

Sample Response for add tag

{
    "response":
          {
           "result":
               {
                "TagDetails":
                    {
                     "message":"TAG_ADDED_SUCCESSFULLY",
                     "tags":"Related to Finance",
                     "taggedDocIds":"docids=cm31c1882749ac9de48518691c0e48111c083"
                    }
               },
                "uri":"/files/v1/tags/add"
          }
}

/remove

Description Removes the tag which is mapped to a document or file
URL Structure https://apidocs.zoho.com/files/v1/tags/remove?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the file to remove the tag
tagname string Mandatory. Name of the tag to be removed from file or document
Returns Returns the success message
Errors 9832 The file wasn't found for the given doc id.
404 User is not valid

Sample Response for remove tag

{
    "response":
          {
            "result":               
               {
                 "message":"TAG_REMOVED_SUCCESSFULLY",
                 "unTaggedDocIds":"docids=cm31c1882749ac9de48518691c0e48111c083"
                },
            "uri":"/files/v1/tags/remove"
          }
}

/delete

Description Deletes the user tags from user account
URL Structure https://apidocs.zoho.com/files/v1/tags/delete?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
tagid long Mandatory. Id of the tag to be deleted
Returns Returns the success message
Errors 404 User is not valid

Sample Response for delete tag

{
    "response":
            {
                "result":
                        {
                            "message":"TAG_DELETED_SUCCESSFULLY"
                        }
                ,"uri":"/files/v1/tag/delete"
            }
}

Workspaces

/workspaces

Description Retrieves the list of user's workspaces(owned and shared).
URL Structure https://apidocs.zoho.com/files/v1/workspaces?authtoken=AuthToken&scope=docsapi
Method GET
Returns Returns the list of workspaces
Errors 404 User is not valid

Sample Response for workspaces

{
    "workspaces":
         [
           {
            "wsname":"Sales","description":"Seller Documents",
            "type":"owned",
            "wsid":"lw5f765ac9d00b5104c2a94ace0578c0894a2"
           },
           {
            "wsname":"Inventory Update",
            "authorid":"3963303",
            "type":"shared",
            "wsid":"lw5f7740917a6ebac4e738e020cdbf272ffe8"
           }
         ]
}

/files

Description Retrieves the list of files and folders in workspace
URL Structure https://apidocs.zoho.com/files/v1/workspaces/files?authtoken=AuthToken&scope=docsapi
Method GET
Parameters
ParameterValueDescription
wsid string Mandatory. Id of the workspace to retrieve the files list.
folderid string Optional. Id of the folder to list the files.
Returns Returns the list of files and folders
Errors 404 User is not valid
9842 Workspace is not found for the given given wsid

Sample Response for workspaces Files

{
    "FILES":[
        {
         "WORKSPACE_ID":"3yprg74fe81ca3d7b419e8dceb32890c84aca",
         "SCOPE":1,
         "FILETYPE":"file",
         "IS_DOC_AUTHOR":false,
         "SHARED_WS_ID":"3yprg74fe81ca3d7b419e8dceb32890c84aca",
         "SHARED_FOLDER_ID":"3yprg74fe81ca3d7b419e8dceb32890c84aca",
         "AUTHOR_NAME":"tomwill",
         "DOCID":"3yprgd0bfe04b7429444587c653a222006973",
         "FILE_EXTN":"zip",
         "LAST_MODIFIEDTIME":"Jul 16",
         "SERVICE_TYPE":"upload",
         "IS_LOCKED":false,
         "CREATED_TIME":"Jul 16",
         "DOCNAME":"Files of  projects.zip"
         }
        ],
"FOLDER":        [
        {
         "FOLDERID":"3yprg677d13e130a4426c9bb00a1a822b6551",
         "WORKSPACEID":"3yprg74fe81ca3d7b419e8dceb32890c84aca",
         "FOLDERNAME":"Project Requirements"
        }
    ]
}

/create

Description Creates a new workspace in user's account
URL Structure https://apidocs.zoho.com/files/v1/workspaces/create?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
wsname string Mandatory. name of the workspace to be created.
description string Optional. notes for the workspace.
users string Mandatory. List of users to be added to the workspace.
wsrole string - (ROLE_VIEWER | ROLE_COLLABORATOR | ROLE_MODERATOR | ROLE_ADMIN) Mandatory. Role for the users added to the workspace.
notifyuser boolean - (true|false) Optional. To notify users in workspace.
Returns Returns the workspace on success
Errors 404 User is not valid

Sample Response for create workspace

{
    "response":
          {
           "result":
               {
                 "message":"WORKSPACE_CREATED_SUCCESSFULLY",
                 "WS_ID":"3yprgcec3ac28f130419dae6bd149d4e44e8a",
                 "CREATED_TIME_MILLISECONDS":"1377768809150",
                 "CREATED_TIME":"3:00 PM"
                },
           "uri":"/files/v1/workspaces/create"
          }
}

/update

Description Updates the existing workspace
URL Structure https://apidocs.zoho.com/files/v1/workspaces/update?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
wsid string Mandatory. Id of the workspace to be updated
wsname string Optional. name of the workspace.
description string Optional. notes for the workspace.
Returns Returns the success message
Errors 9841 Workspace is not found for the given given wsid.
404 User is not valid

Sample Response for update workspace

{
    "response":
          [
            {
             "message":"WorkSpace Renamed Successfully"
            },
            {"result":
               [
                  {"workspacename":"Product Documents"},
                  {"workspaceid":"3yprgcec3ac28f130419dae6bd149d4e44e8a"}
               ]
             },
             {
               "uri":"/files/v1/workspaces/update"
              }
           ]
}

/users

Description Updates the user permission in the workspace
URL Structure https://apidocs.zoho.com/files/v1/workspaces/users?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
wsid string Mandatory. Id of the workspace to be updated with the users list
action string - (add|update|delete) Mandatory. shared users are updated based upon the action.
users string Mandatory. List of users to be added to the workspace.
wsrole string - (ROLE_VIEWER | ROLE_COLLABORATOR | ROLE_MODERATOR | ROLE_ADMIN) Mandatory. Role for the users added to the workspace.
Returns Returns the success message
Errors 9841 Workspace is not found for the given given wsid.
404 User is not valid

Sample Response for users update in workspace

{
    "response":
           {"result":
                {
                 "workspaceId":"8tw2g36f4af0f79384e8495d9154a6b5eabe9",
                 "message":"USER(S) ROLE UPDATED SUCCESSFULLY",
                 "sharedUsers":"tomhill@abc.com"
                },
                   "uri":"/files/v1/workspaces/users"
            }
}

/share

Description Shares a document to the workspace
URL Structure https://apidocs.zoho.com/files/v1/workspaces/share?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
wsid string Mandatory. Id of the workspace to be updated
docid string Mandatory. Id of the document to be added to the workspace.
Returns Returns the success message
Errors 404 User is not valid
9842 Workspace is not found for the given given wsid.
9832 Document Id is not found for the given docId.

Sample Response for share a file in workspace

{
    "response":
           {
            "result":                {
                 "message":"DOCUMENT_SHARED_SUCCESSFULLY",
                 "WORKSPACE_ID":"3yprgcec3ac28f130419dae6bd149d4e44e8a",
                 "DOCUMENT_ID":"3yprg7adc992a0f4d448e830934cc63a780f6",
                 "WORKSPACE_NAME":"Seller Documents"
                },
            "uri":"/files/v1/workspaces/share"
           }
}

/delete

Description Delete a workspace
URL Structure https://apidocs.zoho.com/files/v1/workspaces/delete?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
wsid string Mandatory. Id of the workspace to be deleted
Returns Returns the success message
Errors 404 User is not valid
9842 Workspace is not found for the given given wsid.

Sample Response for delete a workspace

{
        "response": 
            {"result":
                {
                    "message":"WORKSPACE_DELETED_SUCCESSFULLY"
                },
                "uri":"/files/v1/workspaces/delete"
            }
     }

Publish

/publish

Description Publishes a document to public or to the organization
URL Structure https://apidocs.zoho.com/files/v1/publish?authtoken=AuthToken&scope=docsapi
Method POST
Parameters
ParameterValueDescription
docid string Mandatory. Id of the document to be published.
action string - (external|org|change|remove) Mandatory. Any of the given values to publish
type string - (org|external) Mandatory. This parameter is set when publish type is changed from external to org or vice versa
filename string Mandatory. Name of the document to be published
Returns Returns the publish URL on success
Errors 404 User is not valid
9820 Not a valid file name
9821 Not a valid action parameter
9850 User not part of Org to publish within Organization
9832 Document Id is not found for the given docId.
9402 File Not supported for publish option.
Notes This API supports for image and PDF files only.

Sample Response for publish

{
    "response":
           {
            "result":
                {"PublishURL":                           
                    {
                        "MESSAGE":"https://docs.zoho.com/file/3yprg7adc992a0f4d448e830934cc63a780f6"
                    }
                }
           ,"uri":"/files/v1/publish"
           }
}

Error Codes

CodesDescription
404 Not a valid user
500 Internal server error
9832 Invalid Document Id
9830 The start parameter was not set correctly
9831 The limit parameter was not set correctly
9837 Missing Content
9838 Restore Document Failed
9839 The given email id's is not valid
9834 The visibility parameter is not valid
9840 Virus affected file
9820 Not a valid file name
9821 Not a valid action parameter
9850 User not part of Org to publish within Organization
9402 File Not supported for publish option

Smart & Easy Document Management Solution Upgrade, downgrade or cancel at anytime. Plans start at $5/user.

Sign Up Now!
Features
Resources
Popular Links
Recent Blog Posts
Spread the Word

© 2014, ZOHO Corp. ,