File resource

Share file API - Share via email

OVERVIEW

Purpose

This API method is used to share files / folders via email

Request URL :

POST   /shares/email

Sample request URL : https://domain.com/instance/api/1/shares/email

Request Body

Parameter Type Description
resourcetype String The type of the resource which is to be shared. This is a text field with two possible entries "folder" or "file"
resourceid int The Id of the resource to share. The resource ID can be obtained by using the file or folder information methods
permissions  int

There are two possible options 

1 = Download, view or print

2 =  View only

If the system settings are configured to only allow view rights then the above permissions will be overridden by the system to only allow document view. 
share_with string

List of email addresses to share with {these should be valid existing Collaborate users, please see the response specification to determine the error message structure}
expiry date This is the UTC date and time when this share will expire. Expiry date must be greater than current date. In order to set the link to never expire, set the expiry date and time to 31 Dec 9999 00:00" .
 
shareoption integer

Possible values are

1 = Can be accessed by anyone who has the link

2 = Restrict access to specified system users below ( user list specified in share_with parameter) 

3 = Recipients must be registered to access the link
emailsubject string Email subject line
emailmessage string Plain text message only

 

 <share> 

                           <resource_type>folder/file</resource_type> {folder is required in case we want to share a folder already present in Collaborate}

                           <resource_id>folder/file</resource_id>

                           <permissions> integer value for the two options (download / view)</permissions>

                          <share_with>list of email addresses to share with {these should be valid existing Collaborate users,  please see the response specification to determine the error message structure}</share_with>

                          <shareoption> integer value for the options</shareoption> {1(Can be accessed by anyone who has the link) / 2(Restrict access to specified system users below) / 3(Recipients must be registered to access the link)}

                          <emailsubject>Any subject line</emailsubject>
                         

                          <emailmessage>plain text message only</emailmessage>

                          <expiry>UTC date and time</expiry>

 <share>

Example Request XML:

<share>
   <resourcetype>file</resourcetype>
   <resourceid>425</resourceid>
   <permissions>1</permissions>
   <sharewith>
      <emaillist>
         <email>mohiz.tank@highqsolutions.com</email>
         <email>luke.andrews@highqsolutions.com</email>
      </emaillist>
   </sharewith>
   <shareoption>3</shareoption>

   <emailsubject>This is my file</emailsubject>
   <emailmessage>This is my message</emailmessage>
   <expiry>31 Dec 9999 00:00</expiry>
</share>

 

Response XML:
 

Field Type Description
shareid int ID of the newly created share
shared_with string Email address of the person with whom the private message has been shared. 

200 Ok in case of a success an alternate error response otherwise. In case of success the response body will hold the share details. 

In case of an error our standard error object will be returned with explanation of the error.  

<shares>

                <share>

                             <share_id>{id of the share}</share_id> {database id}

                             <shared_with>email address</shared_with> 

                </share>

</shares>
 

Example Response XML:

<shares>
   <share>
      <shareid>223</shareid>
      
      <sharedwithemail>mjtcrop1@highqsolutions.com</sharedwithemail>
   </share>
   <share>
      <shareid>224</shareid>
      
      <sharedwithemail>luke.andrews@highqsolutions.com</sharedwithemail>
   </share>
</shares>

Response Code

Code Meaning
200 Response successfully
401 Unauthorized
403 Validation failed/ Forbidden
405 Method not allowed (calling api with wrong method)
500 Internal error occured while uploading document
 

 

Comments


2 Comments

Hi, for some reason I keep getting the following error when i make a post request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Items>
    <status>415</status>
    <message>Unsupported Media Type</message>
    <categories/>
</Items>

This is my request

<share>
   <resourcetype>file</resourcetype>
   <resourceid>2139</resourceid>
   <permissions>1</permissions>
   <sharewith>
      <emaillist>
         <email>fernando.deleon@corrs.com.au</email>
      </emaillist>
   </sharewith>
   <shareoption>3</shareoption>
   <emailsubject>This is my file</emailsubject>
   <emailmessage>This is my message</emailmessage>
   <expiry>31 Dec 9999 00:00</expiry>
</share>

resourceid is an existing file id (pdf document)

this is the end point i am using

https://corrsuat.highq.com/corrsuat/api/1/shares/email

My headers have

Auth-Type OATH2

Authorization Bearer xxxxx

The authorization is correct because i can fetch site list with no problem.

Last Updated: Jun 09,2023