File resource

Share file API - Share via private message

OVERVIEW

Purpose


This API method is used to share files / folders using a private message. 

Request URL :

POST   /shares/message

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

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" .
 
private_message string Message text to be sent using a private message, The message can accept # and @ mention

 

 <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>

                          <private_message>Message to sent through private message</private_message> {The message can accept # and @ mention}

                          <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>
   <privatemessage>Message sent using the private message [~saviz.izadpanah@highq.com] [#highq]</privatemessage>
   <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. 
message_id int This is a reference to the newly created private message, this is a reference to the activity item in the activity API. The user can use this id to make changes to the private message if needed. 
 

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> 

                             <message_id> </message_id> Reference ID of the newly created private message, this is referred to as activity_id in activity API, The purpose of returning that id in the method call is to allow a reference to the private message if needed. 

                </share>

</shares>
 

Example Response XML:

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

Response Code

Code Meaning
200 Share via private message successfully
400 Problem with parsing XML or JSON object (Bad Request)
401 Unauthorized
403 Validation failed/ Forbidden
405 Method not allowed (calling api with wrong method)
500 Internal error occured

 

Comments


0 Comments

Last Updated: Nov 08,2024