Errors Codes

Zoho Docs APIs

The Zoho Docs APIs provide partners and organizations with a more tightly integrated means of interacting with Zoho's applications for secure storage and document editing functionalities.

Zoho Docs APIs 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 editing capabilities using integrated Zoho services. The Zoho Docs APIs provide a means for document storage and document editing so that partners can focus on their core applications and services rather than build and manage a storage solution.

Zoho Docs offers the following APIs:

Authentication

Auth Tokens and OAuth are currently used to authorize third-party applications to access Zoho Docs. Support for Auth tokens will soon be discontinued, and we recommend switching to Zoho OAuth for better security and control.

 

Zoho OAuth generates two tokens, Refresh and Access tokens. Access tokens are used to authenticate your apps on Zoho Docs and expire after an hour. Refresh tokens allow you to generate new access tokens.

 

Initial Setup

Before you get started, you'll have to register with us and set the application up.

  1. Register your application with our Zoho Accounts team.
  2. Go to https://accounts.zoho.com/developerconsole.
  3. Click Add Client ID.
  4. Enter your application's name, domain, authorized redirect URIs, and click Create.
  5. You will receive Client ID and Client Secret.
  6. You will have to construct a URL to generate a grant token. Click the "Generate Grant Token" section below to learn about the parameters required to construct the URL.
  7. Hit the constructed URL on your browser.
  8. Confirm whether your application can access the ZohoDocs APIs.


     
  9. Once you accept, you will receive a code (grant token) as a query string in the redirect URL.
  10. Get an access token and a refresh token by exchanging the code along with the Client ID and Client Secret.

Note:

Client ID: A unique identifier you receive when you register your application with Zoho. 
Client Secret: A unique key generated when you register your application with Zoho. This must be kept confidential.
Client Name: Enter a name for your app. This is the name that users will see when asked to grant access to your application, and when they check the list of third-party apps that have access to their Zoho Accounts.
Client Domain: Enter your valid domain for Zoho Accounts reference.
Authorized redirect URI: The URI endpoint to which Zoho Accounts has to redirect the user-agent with the access token after authorizing the client.

Generate Grant Token

Method: POST
API: https://accounts.zoho.com/oauth/v2/auth

Query parameters:

PARAMETERSDESCRIPTION
scope
(mandatory)
The specific module in the product for which the access has to be granted.
client_id
(mandatory)
The client ID received during registration. It is used to identify the application that raises the request.
stateA string used by the client to ensure authenticity between the request and callback. It is a recommended parameter that’s used to prevent cross-site request forgery.
response_type
(mandatory)
code
redirect_uri
(mandatory)
The Redirect URI provided during registration.
access_typeSet value as offline

Note: For scope param
The minimum OAuth SCOPE required by each API is mentioned in the SCOPE section of that API. 
If your OAuth token takes more than one scope then include them as a comma-separated list as a 
scope param.

For state param -  is optional, An opaque string that is round-tripped in the protocol; ie., whatever 
value given to this will be passed back to you. e.g., testing

E.g., "ZohoPC.files.READ,ZohoPC.files.CREATE", else if you require all the defined 
scopes use "ZohoPC.files.ALL".

Get Access and Refresh token

Method: POST
API: https://accounts.zoho.com/oauth/v2/token

Query parameters:

PARAMETERSDESCRIPTION
code
(mandatory)
The code that you are exchanging for an access token.
client_id
(mandatory)
The Client ID received during registration. It is used to identify the application that raises the request.
client_secret
(mandatory)
The Client Secret received during registration.
redirect_uri
(mandatory)
The Redirect URI provided during registration.
grant_type
(mandatory)
authorization_code

Regenerate Access token

Access tokens expire after an hour of generation. To generate a new access token, use the refresh token you generated earlier.

Method: POST
API: https://accounts.zoho.com/oauth/v2/token

Query parameters:

PARAMETERSDESCRIPTION
refresh_token
(mandatory)
The refresh token obtained in this get Access and Refresh token.
client_id
(mandatory)
The Client ID received during registration. It is used to identify the application that raises the request.
client_secret
(mandatory)
The Client Secret received during registration.
redirect_uri
(mandatory)
The Redirect URI provided during registration.
grant_type
(mandatory)
refresh_token

Scopes

In OAuth 2.0, scope is a mechanism to limit the client application's access to protected resources.

 

OAuth ScopePurpose
ZohoPC.files.CREATETo create files/folder (eg: upload,create)
ZohoPC.files.READTo get the list of files/folders (eg: get list)
ZohoPC.files.UPDATETo update files/folders (eg: rename)
ZohoPC.files.DELETETo delete files/folders (eg: trash)

 

Upload Files

/upload

DescriptionUploads a file using POST semantics.
URL Structurehttps://apidocs.zoho.com/files/v1/upload
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
filenamestringMandatory. Name of the file to be uploaded
fidstringOptional. id of the folder where files to be uploaded to a folder
wsidstringOptional. id of the workspace where files to be uploaded to a workspace
contentstringMandatory. Actual document content to be uploaded
ReturnsReturns the meta data of the uploaded document
Errors404 User is not valid
9837 Missing Content
NotesThis API supports maximum file size limit of 100 MB for free users and 250 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

DescriptionDownloads a file.
URL Structurehttps://apidocs.zoho.com/files/v1/content/<DOC_ID>
OAuth ScopeZohoPC.files.READ
MethodGET
Parameters
ParameterValueDescription
docversionstringOptional. Version of the document to be downloaded. This defaults to recent one.
ReturnsThe specified file's content with the requested version.
Errors9832 The file wasn't found for the given doc id.

Manage File Metadata

/create

DescriptionCreates a new document or file
URL Structurehttps://apidocs.zoho.com/files/v1/create
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
filenamestringMandatory. Name of the file to be created
servicestring - (document | spreadsheet | presentation)Mandatory. Any of the given service
typestring - (doc | template)Mandatory. Specify the type to create a template or document
parentfolderidstringOptional. Id of the folder in which document to be created. This takes default as root folder.
ReturnsReturns the success message
Errors404 User is not valid
9822 Not a valid service type specified
9823 Error while creating a document

/files

DescriptionRetrieves the user's files
URL Structurehttps://apidocs.zoho.com/files/v1/files
OAuth ScopeZohoPC.files.READ
MethodGET
Parameters
ParameterValueDescription
categorystring - (documents | spreadsheets | presentations | pictures | music | videos | sharedbyme | sharedtome | thrashed)Optional. List of files based on category
startintegerOptional. This value is set to get the list of files from that entry
limitintegerOptional. 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.
ReturnsSpecified category files.
Errors404 User is not valid
9830 The start parameter was not set correctly
9831 The limit parameter was not set correctly
NotesThis 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

DescriptionCopies a file or document to a new location
URL Structurehttps://apidocs.zoho.com/files/v1/copy
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to be copied
folderidstringMandatory. Id of folder to copy the new file
ReturnsReturns the Success message
Errors404 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

DescriptionMoves a file or document to a specified location
URL Structurehttps://apidocs.zoho.com/files/v1/move
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to be moved
folderidstringMandatory. Id of folder to copy the new file
ReturnsReturns the Success message
Errors404 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

DescriptionMoves the file to trash.
URL Structurehttps://apidocs.zoho.com/files/v1/trash
OAuth ScopeZohoPC.files.DELETE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to be trashed
ReturnsReturns the success message
Errors404 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

DescriptionRestores the file which has been trashed
URL Structurehttps://apidocs.zoho.com/files/v1/restore
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to be restored
ReturnsReturns the success message
Errors404 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

DescriptionFiles will be removed from user's account
URL Structurehttps://apidocs.zoho.com/files/v1/delete
OAuth ScopeZohoPC.files.READ
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to be deleted
ReturnsReturns the success message
Errors404 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

DescriptionRenames the existing file or document
URL Structurehttps://apidocs.zoho.com/files/v1/rename
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to be renamed
docnamestringMandatory. New name for the document or file
ReturnsReturns the success message
Errors404 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

DescriptionShares a file to a private email ID
URL Structurehttps://apidocs.zoho.com/files/v1/share
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
docidsstringMandatory. Id of the document or file to be shared
emailidsstringMandatory. Email ID of the users to share
permissionstring - (readonly|readwrite|coowner)Mandatory. file shared to the user with the specified permission
notifyboolean - (true|false)Optional. notifies the shared user when file or document is shared via email
messagestringOptional. message to the shared user via email
ReturnsReturns the success message
Errors404 User is not valid
9832 The file wasn't found for the given doc id.
9839 The given email ID 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

DescriptionSharing a file via link
URL Structurehttps://apidocs.zoho.com/files/v1/share/visibility
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to be shared via link
visibilitystring - (orglinkshare | orgshare | linkshare | private )Mandatory. To change the document visibility.
permissionstring - (readonly|readwrite)Mandatory. file shared to the user with the specified permission
passwordstringOptional. password required if the doc is shared via link share with secured
expiresondate - (mm/dd/yyyy)Optional. specify the date till the document can be shared via link share
ReturnsReturns the success message with the generated link
Errors404 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

DescriptionUpdates the permission of existing shared file
URL Structurehttps://apidocs.zoho.com/files/v1/share/update
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to updated document visibility
visibilitystring - (orglinkshare | orgshare | linkshare | private )Mandatory. To change the document visibility.
permissionstring - (readonly|readwrite)Mandatory. file shared to the user with the specified permission
emailidsstringOptional. Email ID of the users to share (Mandatory if the visibility is set as private).
ReturnsReturns the success message.
Errors404 User is not valid
9832 The file wasn't found for the given doc id.
9839 The given email ID 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

DescriptionRemoves the share permission for the shared user
URL Structurehttps://apidocs.zoho.com/files/v1/share/remove
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to remove share
emailidsstringMandatory. email ID of the users to share
ReturnsReturns the success message
Errors404 User is not valid
9832 The file wasn't found for the given doc id.
9839 The given email ID is not valid

Sample Response for remove

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

/details

DescriptionReturns the shared details of a document or file
URL Structurehttps://apidocs.zoho.com/files/v1/share/details
OAuth ScopeZohoPC.files.READ
MethodGET
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document or file to get shared details
ReturnsReturns the share details
Errors9832 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

DescriptionRevises the content of the existing file using POST semantics.
URL Structurehttps://apidocs.zoho.com/files/v1/revision
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document to be revision
filenamestringMandatory. Name of the file to be revision.
contentstringMandatory. content of the file to upload
ReturnsReturns the Success message
Errors404 User is not valid
9837 Missing Content
NotesThis 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

DescriptionLists the revision details for the given document.
URL Structurehttps://apidocs.zoho.com/files/v1/revision/details
OAuth ScopeZohoPC.files.READ
MethodGET
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document to be revision
typestring - (owned|shared)Mandatory. specify which type of document.
ReturnsReturns the list of version details on success
Errors404 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

DescriptionReturns the list of folders present in user's account
URL Structurehttps://apidocs.zoho.com/files/v1/folders
OAuth ScopeZohoPC.files.READ
MethodGET
Parameters
ParameterValueDescription
folderidstringOptional. Id of the folder to get sub folder list. This takes default as root folder
ReturnsReturns the folders list
Errors404 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

DescriptionCreates a new folder.
URL Structurehttps://apidocs.zoho.com/files/v1/folders/create
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
foldernamestringMandatory. Name of the folder in which folder to be created.
parentfolderidstringOptional. Id of the folder in which folder to be created. This takes default as root folder.
ReturnsReturns the newly created folder id
Errors404 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

DescriptionRenames the existing folder
URL Structurehttps://apidocs.zoho.com/files/v1/folders/rename
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Id of the folder to be renamed
foldernamestringMandatory. New name for the folder
ReturnsReturns the success message
Errors404 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

DescriptionMoves the existing folder to specified location
URL Structurehttps://apidocs.zoho.com/files/v1/folders/move
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Id of the folder to be moved
destfolderidstringMandatory. Id of the folder to be moved
prevparentfolderidstringMandatory. Id of the folder in which current folder was present.
ReturnsReturns the success message
Errors404 User is not valid

Sample Response for move folder

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

/copy

DescriptionCopies the existing folder to a specified folder
URL Structurehttps://apidocs.zoho.com/files/v1/folders/copy
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Copies folder I.D
destfolderidstringMandatory. Specifies I.D of the destination folder (where existing folder copies).
ReturnsReturns the success message
Errors404 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

DescriptionFolder will be moved to trashed
URL Structurehttps://apidocs.zoho.com/files/v1/folders/trash
OAuth ScopeZohoPC.files.DELETE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Id of the folder to be trashed
ReturnsReturns the success message
Errors404 User is not valid

Sample Response for trash folder

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

/restore

DescriptionRestores the folder which has been trashed
URL Structurehttps://apidocs.zoho.com/files/v1/folders/restore
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Id of the folder to be restored
ReturnsReturns the success message
Errors404 User is not valid

Sample Response for restore folder

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

/delete

DescriptionDeletes the folder from User's account
URL Structurehttps://apidocs.zoho.com/files/v1/folders/delete
OAuth ScopeZohoPC.files.DELETE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Id of the folder to be deleted
ReturnsReturns the success message
Errors404 User is not valid

Sample Response for delete folder

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

/files

DescriptionRetrieves the files and folders present in that folder
URL Structurehttps://apidocs.zoho.com/files/v1/folders/files
OAuth ScopeZohoPC.files.READ
MethodGET
Parameters
ParameterValueDescription
folderidstringOptional. Id of the folder to retrieve the list. This takes default as my folder.
ReturnsReturns the list of files and folder
Errors404 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

DescriptionShare folders to private email IDs
URL Structurehttps://apidocs.zoho.com/files/v1/share
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
folderidsstringMandatory. Specifies Folder I.D
emailidsstringMandatory. Specifies email IDs of the users to be shared
permissionstring - (readonly|readwrite | coowner)Mandatory. Specifies the access permission for the shared folder.
notifyboolean - (true|false)Optional. Notifies the shared user when a folder is shared via email
messagestringOptional. Message is sent to the shared user via email.
ReturnsReturns the success message
Errors404 User is not valid.
9832 The folder was not found for the given folderid.
9839 The given email IDs are not valid.

Sample Response for Share Folder

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

/visibility

DescriptionSharing a folder via link
URL Structurehttps://apidocs.zoho.com/files/v1/share/visibility
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Folder I.D is shared through link.
visibilitystring - (orglinkshare | orgshare | linkshare | private )Mandatory. Changes folder visibility
permissionstring - readonly | readwriteMandatory. Folder is shared to the user with the specified permission.
passwordstringOptional. Password is required if the folder is shared via link and password protected.
expiresondate - (mm/dd/yyyy)Optional. Specifies the date till the folder can be accessed via link.
ReturnsReturns the success message with the generated link
Errors404 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

DescriptionUpdates the permission of existing shared folder
URL Structurehttps://apidocs.zoho.com/files/v1/share/update
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Specify folder I.D to change the existing permission/visibilty.
visibilitystring - (orglinkshare | orgshare | linkshare | private )Mandatory. Changes the folder visibility
permissionstring - readonly | readwrite | coownerMandatory. Folder is shared to the user with the specified permission.
emailidsstringOptional. Share user email ID (Mandatory, if the visibility is set as private).
ReturnsReturns the success message.
Errors404 User is not Valid
9832 The folder was not found for the given folderid.
9839 The given email IDs 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

DescriptionRemoves the share permission for the shared user
URL Structurehttps://apidocs.zoho.com/files/v1/share/remove
OAuth ScopeZohoPC.files.UPDATE
MethodPOST
Parameters
ParameterValueDescription
folderidstringMandatory. Specify folder IDs to remove sharing.
emailidsstringMandatory. Share user email IDs.
ReturnsReturns the success message.
Errors404 User is not Valid
9832 The folder was not found for the given folder id.
9839 The given email IDs are not valid

Sample Response for Remove

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

/details

DescriptionReturns the shared details of a folder
URL Structurehttps://apidocs.zoho.com/files/v1/share/details
OAuth ScopeZohoPC.files.READ
MethodGET
Parameters
ParameterValueDescription
folderidstringMandatory. Specify Folder I.D to get shared details.
ReturnsReturns the share details
Errors9832 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

DescriptionReturns the list of user tags
URL Structurehttps://apidocs.zoho.com/files/v1/tags
OAuth ScopeZohoPC.files.CREATE
MethodGET
ReturnsReturns the list of user tags
Errors404 User is not valid

Sample Response for tags

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

/create

DescriptionCreates a new user tag
URL Structurehttps://apidocs.zoho.com/files/v1/tags/create
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
tagnamestringMandatory. Name of the tag to create.
ReturnsReturns the Tag Id
Errors404 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

DescriptionAdds a tag to a file or a document
URL Structurehttps://apidocs.zoho.com/files/v1/tags/add
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the file to which tag should be added
tagnamestringMandatory. Name of the tag to be added.
ReturnsReturns the success message.
Errors9832 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

DescriptionRemoves the tag which is mapped to a document or file
URL Structurehttps://apidocs.zoho.com/files/v1/tags/remove
OAuth ScopeZohoPC.files.DELETE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the file to remove the tag
tagnamestringMandatory. Name of the tag to be removed from file or document
ReturnsReturns the success message
Errors9832 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

DescriptionDeletes the user tags from user account
URL Structurehttps://apidocs.zoho.com/files/v1/tags/delete
OAuth ScopeZohoPC.files.DELETE
MethodPOST
Parameters
ParameterValueDescription
tagidlongMandatory. Id of the tag to be deleted
ReturnsReturns the success message
Errors404 User is not valid

Sample Response for delete tag

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

Publish

/publish

DescriptionPublishes a document to public or to the organization
URL Structurehttps://apidocs.zoho.com/files/v1/publish
OAuth ScopeZohoPC.files.CREATE
MethodPOST
Parameters
ParameterValueDescription
docidstringMandatory. Id of the document to be published.
actionstring - (external|org|change|remove)Mandatory. Any of the given values to publish
typestring - (org|external)Mandatory. This parameter is set when publish type is changed from external to org or vice versa
filenamestringMandatory. Name of the document to be published
ReturnsReturns the publish URL on success
Errors404 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.
NotesThis 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
404Not a valid user
500Internal server error
9832Invalid Document Id
9830The start parameter was not set correctly
9831The limit parameter was not set correctly
9837Missing Content
9838Restore Document Failed
9839The given email addresses are not valid
9834The visibility parameter is not valid
9840Virus affected file
9820Not a valid file name
9821Not a valid action parameter
9850User not part of Org to publish within Organization
9402File Not supported for publish option

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohodocs.com