Share APIs




This topic is deprecated. Please access the new set of "Share APIs" from over here: "https://www.zoho.com/docs/zoho-docs-api.html#share" 





Share APIs

Zoho Share APIs allow you to share a spreadsheet or a presentation with a set of users as well as define access privileges for them. You can decide whether the shared user can view or edit the shared document based on the access privilege. There's a cancel sharing method too in case you want to revoke sharing permission for a particular user. As these methods involve a write request, you are required to do a HTTPS multi-part form POST with a few additional parameters.

Methods List:
  1. Share a private document
  2. Cancel document share for a particular user

Share a private document

 Request URI : (HTTPS POST)

Developers can send the request for sharing documents in the following URI format :

 Zoho Sheet (Spreadsheets):
https://sheet.zoho.com/api/<access>/<format>/shareBook/workbookId?apikey=[API Key]&authtoken=[AuthToken]&scope=DataAPI
Zoho Show (Presentations):
https://show.zoho.com/api/<access>/<format>/sharepresentation/presentationId?apikey=[API Key]&authtoken=[AuthToken]&scope=DataAPI
 Access: private

HTTPs Method: POST

Response Formats: xml, json

Form Request Parameters Reference

The following are the parameters that needs to be passed in multi-part HTTPs POST request for Sheet/Show :
Parameter Value
 Description
workbookId / presentationId
 string
 Mandatory. Unique ID of the document that is to be shared.

Note: You can get the 'documentId' from document list api.
shareto
 string
 Mandatory. One or more Zoho IDs/Email IDs of Zoho users to whom the document is to be shared. For adding multiple users, separate them by 'comma'.
allowtowrite
 boolean
 Mandatory. Give access permission for the document to shared shared users. If set to true, the users are allowed 'read/write' access else the shared document opens in read-only mode.

Multi-part Form Submit - Sample

Zoho Show 
<form method="POST" action="https://show.zoho.com/api/private/xml/sharepresentation/presentationId" 
enctype="multipart/form-data" target="_self" accept-charset="UTF-8">
<input type="hidden" name="apikey" value="[Zoho_API_Key]">
<input type="hidden" name ="authtoken" id="authtoken" value="dujj18eba1ff45jk7858b8ae88a77re430">
<input type="hidden" name ="scope" id="scope" value="DataAPI">
<input type="hidden" name="shareto" value="[Zoho IDs/Email IDs]">
<input type="hidden" name="allowtowrite" value="[true/false]">
<input type="submit" name="submit" value="Share">
</form>
Zoho Sheet
<form method="POST" action="https://sheet.zoho.com/api/private/xml/shareBook/workbookId" enctype="multipart/form-data" 
target="_self" accept-charset="UTF-8">
<input type="hidden" name="apikey" value="[Zoho_API_Key]">
<input type="hidden" name ="authtoken" id="authtoken" value="dii18eba1ff45jk7858b8ae88a77fa30">
<input type="hidden" name ="scope" id="scope" value="DataAPI">
<input type="hidden" name="readOnlyUsers" value="[Username]">
<input type="hidden" name="readWriteUsers" value="[Username]">
<input type="submit" name="submit" value="Share">
</form>

Response Parameters Reference
 
Parameter Value
 Description
workbookId / presentationId
 integer
 Unique ID associated with the spreadsheet or presentation that is being shared.
workbookName / presentationName
 string
 Name of the spreadsheet or presentation that is being shared.
sharedto
 string
 List of users to whom the document has been shared.

Sample Response :

The following is a response (both in XML & JSON) for share document method:

XML 
<?xml version="1.0" encoding="UTF-8" ?> 
<response uri="/api/private/xml/shareBook">
  <result>

     <workbookId>15265000000006107</workbookId>
     <workbookName>Financials</workbookName>
     <sharedto>
            <user>"derrick"</user>
            <user>"simon"</user>
            <user>"martha"</user>
     </sharedto>

  </result>
</response>
JSON
{
  "response": 
   {
        "uri": "/api/private/json/shareBook",
        "result":
        { 
            "workbookId":"15265000000006107",
            "workbookName":"Financials",
            "sharedto":
             {
                "user":
                [
                     {"derrick"}, {"simon"}, {"martha"}  
                ]
             } 
            
        }
    }
}

Cancel document share

 Request URI : (HTTPs POST)

In order to revoke sharing privilege of a particular user, developers need to send request in the following URI format :


Zoho Sheet (Spreadsheets) :
https://sheet.zoho.com/api/<access>/<format>/cancelsharing/[workbookId]?apikey=[API Key]&authtoken=[AuthToken]&scope=DataAPI
Zoho Show (Presentations) :
https://show.zoho.com/api/<access>/<format>/cancelsharing/[presentationId]?apikey=[API Key]&authtoken=[AuthToken]&scope=DataAPI
Access: private

HTTPs Method: POST

Response Formats : xml, json

Form Request Parameters Reference

The following are the parameters that needs to be passed in multi-part HTTPs POST request for Sheet/Show :
Parameter Value
 Description
workbookId / presentationId
 string
 Mandatory. Unique ID of the shared document.

Note: You can get the 'documentId' from document list api.
emailid
 string
 Mandatory. Email ID/Zoho ID of the user whose sharing access is to be revoked.

Multi-part Form Submit - Sample
<form method="POST" action="https://show.zoho.com/api/private/xml/cancelsharing" enctype="multipart/form-data" 
target="_self" accept-charset="UTF-8">
<input type="hidden" name="apikey" value="[Zoho_API_Key]">
<input type="hidden" name ="authtoken" id="authtoken" value="bad18eba1ff45jk7858b8ae88a77fa30">
<input type="hidden" name ="scope" id="scope" value="DataAPI">
<input type="hidden" name="presentationId" value="[doc id of the shared document]">
<input type="hidden" name="emailid" value="[Email ID/Zoho ID]">
<input type="submit" name="submit" value="CancelShare">
</form>
 Response Parameters Reference

Parameter Value
 Description
workbookId / presentationId
 integer
 Unique ID associated with the shared spreadsheet or presentation.
workbookName / presentationName
 string
 Name of the spreadsheet or presentation whose sharing is to be revoked.

Sample Response :

The following is a response (both in XML & JSON) for the above method:

XML 
<?xml version="1.0" encoding="UTF-8" ?> 
<response uri="/api/private/xml/cancelsharing">
  <result>

     <presentationId>15265000000006107</presentationId>
     <presentationName>Amistad</presentationName>
     
  </result>
</response>
JSON
{
  "response": 
   {
        "uri": "/api/private/json/cancelsharing",
        "result":
        { 
            "presentationId":"15265000000006107",
            "presentationName":"Amistad"
        }
    }
}




    Post a comment

    Your Name or E-mail ID (mandatory)

    Note: Your comment will be published after approval of the owner.



    		 RSS of this page