Shares allows sharefile users to give access to files and folders to other users. Shares are used to "Send" or "Request" files to anonymous or named users, without giving the target direct access to the user folders.Shares contain policies - such as expiration, maximum number of downloads, authentication options.
GET https://account.sf-api.com/sf/v3/Shares
Retrieve all outstanding Shares of the authenticated user
| includeExpired | Boolean | Specifies whether or not expired shares should be returned. Set to true by default |
Returns: List of Shares created by the authenticated user
GET https://account.sf-api.com/sf/v3/Shares(id)?includeExpired=false
Retrieve a single Share entity. Public share access will now require authentication for programmatic access for better security. If the Share is expired the endpoint will respond with 404 Not Found, unless `includeExpired` is set to true. The creator of the Share will fetch an expired Share, regardless of the `includeExpired` value
| id | String | Share ID |
| includeExpired | Boolean | Specifies whether or not expired shares should be returned. Set to false by default |
Returns: A single Share
GET https://account.sf-api.com/sf/v3/Shares(id)/Recipients
Retrieve the list of Recipients in the share. Recipients represent the target users of the Share, containing access information, such as number of times that user downloaded files from the share. Each Recipient is identified by an Alias, which is an unique ID given to each user - allowing tracking of downloads for non-authenticated users.
| id | String | Share ID |
| includeExpired | Boolean | Specifies whether or not expired shares should be returned. Set to false by default |
Returns: A feed of Share Aliases representing recipients of the Share
POST https://account.sf-api.com/sf/v3/Shares(parentid)/Recipients?Email=email&FirstName=firstName&LastName=lastName&Company=company
Creates a Recipient User for a Share that requires user information
| parentid | String | Share ID |
| String | ||
| FirstName | String | |
| LastName | String | |
| Company | String |
Returns: A Share Alias representing a single recipient of the Share
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Items(itemid)/Thumbnail?size=75&redirect=true
Retrieve a thumbnail link for the specified Item in the Share.
| shareid | String | Share ID |
| itemid | String | Item ID |
| size | Int32 | Thumbnail size. Only 75px and 600px are supported. Default is 75px |
| redirect | Boolean | If set to true, the response will be a 302 to the thumbnail URL. Otherwise, it returns 200 OK with a Redirection object in payload |
Returns: A 302 redirection to the Thumbnail link
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Items(itemid)/ProtocolLinks(platform)
| shareid | String | Share ID |
| itemid | String | Item ID |
| platform | String | The platform making the preview request (can be 'all', 'default', 'web', 'webandmobile', 'mobile') |
Returns: A list of protocol links depending on the input parameter 'platform', 404 (Not Found) if not supported by the item
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Download
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Download?Name=username&Email=user@company.com&Company=Acme
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Download?id=itemid
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Download(itemid)
Downloads items from the Share. The default action will download all Items in the Share. If a Share has a single item, the download attachment name will use the item name. Otherwise, the download will contain a ZIP archive containing all files and folders in the share, named Files.zip.
To download Shares that require authentication, make sure this request is authenticated. To download shares that require require user information, provide the Name, Email and Company parameters in the URI query. Public share access will now require authentication for programmatic access for better security.
You can also download individual Items in the Share. Use the Share(id)/Items(id)/Download action. The item ID must be a top-level item in the Share - i.e., you cannot download or address files contained inside a shared folder.
| shareId | String | Share ID |
| itemId | String | Item ID |
| name | String | In the format of FirstName LastName |
| String | ||
| company | String | |
| redirect | Boolean | if true (default), the response is a 302 to the target object. Otherwise, caller recieves a DownloadSpecification object on a 200 return |
Returns: Redirects the caller (302) to the download address for the share contents.
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Recipients(aliasid)/DownloadWithAlias
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Recipients(aliasid)/DownloadWithAlias?id=itemid
GET https://account.sf-api.com/sf/v3/Shares(shareid)/Recipients(aliasid)/DownloadWithAlias(itemid)
Downloads items from the Share. The default action will download all Items in the Share. If a Share has a single item, the download attachment name will use the item name. Otherwise, the download will contain a ZIP archive containing all files and folders in the share, named Files.zip.
To download Shares that require user informaion ( Email, First Name, Last Name and Company), make sure to create an Recipient (alias)
To download Shares that require authentication, make sure this request is authenticated. Public share access will now require authentication for programmatic access for better security.
You can also download individual Items in the Share. Use the Shares(id)/Recipients(aliasid)/Download action. The item ID must be a top-level item in the Share - i.e., you cannot download or address files contained inside a shared folder.
| shareId | String | Share ID |
| aliasid | String | Recipient ID |
| itemId | String | Item ID |
| redirect | Boolean | Redirect to download link if set to true (default), or return a DownloadSpecification object if set to false |
Returns: Redirects the caller (302) to the download address for the share contents.
POST https://account.sf-api.com/sf/v3/Shares(id)/Recipients(aliasid)/BulkDownload?redirect=true
["id1","id2"]
Download Multiple Items from a Share for a Recipient. The download will contain a ZIP archive containing all files and folders in the share, named Files.zip.
To download Shares that require user informaion ( Email, First Name, Last Name and Company), make sure to create an Recipient (alias) and pass in the alaisId.
To download Shares that require authentication, make sure this request is authenticated. Public share access will now require authentication for programmatic access for better security.
| shareId | String | Share ID |
| aliasid | String | Recipient ID |
| ids | String[] | List of items to download. |
| redirect | Boolean | Redirect to download link if set to true (default), or return a DownloadSpecification object if set to false |
| includeExpired | Boolean | Specifies whether or not expired shares should be returned. Set to false by default |
Returns: Redirects the caller (302) to the download address for the share contents.
POST https://account.sf-api.com/sf/v3/Shares?notify=false
{
"ShareType":"Send",
"Title":"Sample Send Share",
"Items": [ { "Id":"itemid01" }, { "Id":"itemid02" } ],
"Recipients":[ { "User": { "Id":"userid" } }, { "User": { "Email": "user@email" } } ],
"ExpirationDate": "2013-07-23",
"RequireLogin": false,
"RequireUserInfo": false,
"MaxDownloads": -1,
"UsesStreamIDs": false
}
POST https://account.sf-api.com/sf/v3/Shares?notify=false
{
"ShareType":"Request",
"Title":"Sample Request Share",
"Recipients":[ { "User": { "Id":"userid" } }, { "User": { "Email": "user@email" } } ],
"Parent": { "Id":"folderid" },
"ExpirationDate": "2013-07-23",
"RequireLogin": false,
"RequireUserInfo": false,
"TrackUntilDate": "2013-07-23",
"SendFrequency": -1,
"SendInterval": -1
}
Creates a new Send or Request Share. Expiration date: - if not specified the default is 30 days - "9999-12-31" disables share expiration.
To use stream IDs as item IDs UsesStreamIDs needs to be set to true, and all the IDs in Items need to be specified as stream IDs.
View Only: View Only share can be created by either setting "IsViewOnly = true" or "share.ShareAccessRight.ShareAccessRightType = ViewOnline" If both "share.IsViewOnly = true" and "share.ShareAccessRight.AccessRightType = FullControl" are passed to this method, then the "Full Control" permission takes higher priority and disables "ViewOnly" permission on the share.
| share | Share | |
| notify | Boolean | |
| direct | Boolean | For third-party data providers, return a direct Uri if set to true, or return a ShareFile Uri if set to false (default). |
Returns: The new Share
PATCH https://account.sf-api.com/sf/v3/Shares(id)?appendItemsFeed=true
{
"Title": "New Title",
"ExpirationDate": "2013-07-23",
"RequireLogin": false,
"Items": [ { "Id":"itemid01" }, { "Id":"itemid02" } ],
}
Modifies an existing Share. If Items are specified they are added to the share by default. If appendItemsFeed is set to false, the specified Items will replace any existing ones instead.
View Only: A share can be made ViewOnline/ViewOnly by passing either "IsViewOnly = true" or "Share.ShareAccessRight.AccessRightType = ViewOnline"
| id | String | |
| share | Share | |
| appendItemsFeed | Boolean | By default the Items feed specified in the PATCH body is appended to the existing feed. When set to false, the specified feed replaces the existing feed. |
| includeExpired | Boolean | False by default. If true, an expired share can be updated. |
Returns: The modified Share
POST https://account.sf-api.com/sf/v3/Shares(id)/Alias?email=user@company.com¬ify=false
Creates a share alias for the specified share ID and user email. If a user with the given email address does not exist it is created first. For shares requiring login an activation email is sent to the created user. If 'notify' is enabled, the user activation is included in the share notification email.
| id | String | share ID |
| String | share recipient email | |
| notify | Boolean | if enabled, a notification email about the share is sent to the recipient |
Returns: Share with the AliasID property set to the created alias ID
POST https://account.sf-api.com/sf/v3/Shares/Send
{
"Items":["itemId1", "itemId2"],
"Emails":["email@sharefile.com", "email2@sharefile.com"],
"Subject": "Email Subject",
"Body": "Email Message",
"CcSender": false,
"NotifyOnDownload": true,
"RequireLogin": false,
"MaxDownloads": 30,
"ExpirationDays": -1
}
Sends an Email to the specified list of addresses, containing a link to the specified Items. The default number of expiration days is 30. Setting it to -1 disables share expiration. Note that the Emails and Items parameters expect an array of strings, rather than nested JSON objects.
| parameters | ShareSendParams | ShareSendParams object. Mandatory parameters are Items, Emails, and Subject. |
Returns: Share object
POST https://account.sf-api.com/sf/v3/Shares/SendCallback
{
"RecipientArray":["email@sharefile.com", "email2@sharefile.com"],
"SfShareId": "SF Share Id",
"ShareSendParams": {
"Items":["itemId1", "itemId2"],
"Emails":["email@sharefile.com", "email2@sharefile.com"],
"Subject": "Email Subject",
"Body": "Email Message",
"CcSender": false,
"NotifyOnDownload": true,
"RequireLogin": false,
"MaxDownloads": 30,
"ExpirationDays": -1
}
}
Called by the analytics service once spam analysis passes. Requires the “analytics” client_id claim to prevent unauthorized use.
| parameters | ShareSendPostBackParams | ShareSendCallbackParams object containing Items, Emails, Subject, etc., plus CorrelationId. |
Returns: The Share that was sent.
POST https://account.sf-api.com/sf/v3/Shares/Request
{
"FolderId":"folderId",
"Emails":["email@sharefile.com", "email2@sharefile.com"],
"Subject": "Email Subject",
"Body": "Email Message",
"CcSender": false,
"NotifyOnUpload": true,
"RequireLogin": false,
"ExpirationDays": -1
}
Sends an Email to the specified list of addresses, containing a link to upload to the specified folder. The default number of expiration days is 30. Setting it to -1 disables share expiration. Note that the Emails parameter expectd an array of strings, rather than nested JSON objects.
View Only: View Only share can be created by either setting "IsViewOnly = true" or "share.ShareAccessRight.ShareAccessRightType = ViewOnline" If both "share.IsViewOnly = true" and "share.ShareAccessRight.AccessRightType = FullControl" are passed to this method, then the "Full Control" permission takes higher priority and disables "ViewOnly" permission on the share.
| parameters | ShareRequestParams | ShareRequestParams object. Mandatory parameters are FolderId or FolderPath, Emails, and Subject. |
Returns: Share Object
POST https://account.sf-api.com/sf/v3/Shares/Resend
{
"Recipients":["email@sharefile.com", "groupId"],
"Subject": "Email Subject",
"Body": "Email Message",
"CcSender": false,
"NotifyOnUse": true,
"ShareId": "shareId"
}
Resends an Email to the specified list of addresses, containing a link to a Send or Request Share
| parameters | ShareResendParams | ShareResendParams object. Mandatory parameters are Share ID, Subject, and 1+ recipients (email address or distribution group) |
Returns: The updated Share
POST https://account.sf-api.com/sf/v3/Shares(id)/Upload?method=method&various...
POST https://account.sf-api.com/sf/v3/Shares(id)/Upload2
{
"Method":"Method",
"Raw": false,
"FileName":"FileName",
"FileLength": 123
}
Prepares the links for uploading files to the target Share. This method returns an Upload Specification object. The fields are populated based on the upload method, provider, and resume parameters passed to the upload call. The Method determines how the URLs must be called.
Standard uploads use a single HTTP POST message to the ChunkUri address provided in the response. All other fields will be empty. Standard uploads do not support Resume.
Streamed uploads use multiple HTTP POST calls to the ChunkUri address. The client must append the parameters index, offset and hash to the end of the ChunkUri address. Index is a sequential number representing the data block (zero-based); Offset represents the byte offset for the block; and hash contains the MD5 hash of the block. The last HTTP POST must also contain finish=true parameter.
Threaded uploads use multiple HTTP POST calls to ChunkUri, and can have a number of threads issuing blocks in parallel. Clients must append index, offset and hash to the end of ChunkUri, as explained in Streamed. After all chunks were sent, the client must call the FinishUri provided in this spec.
For all uploaders, the contents of the POST Body can either be "raw", if the "Raw" parameter was provided to the Uploader, or use MIME multi-part form encoding otherwise. Raw uploads simply put the block content in the POST body - Content-Length specifies the size. Multi-part form encoding has to pass the File as a Form parameter named "File1".
For streamed and threaded, if Resume options were provided to the Upload call, then the fields IsResume, ResumeIndex, ResumeOffset and ResumeFileHash MAY be populated. If they are, it indicates that the server has identified a partial upload with that specification, and is ready to resume on the provided parameters. The clients can then verify the ResumeFileHash to ensure the file has not been modified; and continue issuing ChunkUri calls from the ResumeIndex ResumeOffset parameters. If the client decides to restart, it should simply ignore the resume parameters and send the blocks from Index 0.
For all uploaders: the result code for the HTTP POST calls to Chunk and Finish Uri can either be a 401 - indicating authentication is required; 4xx/5xx indicating some kind of error; or 200 with a Content Body of format 'ERROR:message'. Successful calls will return either a 200 response with no Body, or with Body of format 'OK'.
| id | String | Target Share identifier |
| method | UploadMethod | Upload method: one of: standard, streamed or threaded |
| raw | Boolean | If true, the uploader will send file contents directly in the POST body of the returned upload links. If false, the uploader will send contents in MIME format. Default is false |
| fileName | String | Uploaded item file name. May be null if the metadata is contained in MIME body, or ZIP file upload, then filename may be null. Is mandatory for single file, raw uploads. |
| fileSize | Int64 | Uploaded item file size. Same as filename - may be ignored if metadata is contained somewhere else. |
| batchId | String | Inidicates that this upload is part of a batch. Batched uploads do not send notification until the whole batch is completed. |
| batchLast | Boolean | Indicates that this upload is the last in a batch. Upload notifications for the whole batch are sent after this upload. |
| canResume | Boolean | Indicates that the uploader supports resume. |
| startOver | Boolean | Indicates that the uploader wants to restart the file - i.e., ignore previous failed upload attempts. |
| tool | String | Identifies the uploader tool. |
| overwrite | Boolean | Indicates whether items with the same name will be overwritten or not. |
| title | String | Item Title |
| details | String | Item description |
| isSend | Boolean | Indicates that this upload is part of a Send operation |
| sendGuid | String | Used if IsSend is true. Specifies which Send operation this upload is part of. |
| opid | String | Used for Asynchronous copy/move operations - called by Zones to push files to other Zones |
| threadCount | Int32 | Specifies the number of threads the threaded uploader will use. Only used is method is threaded, ignored otherwise |
| responseFormat | String | Configures the response format for the upload link calls. Default is json. |
| notify | Boolean | Indicates whether users will be notified of this upload - based on folder preferences |
| clientCreatedDateUTC | DateTime? | client filesystem Created Date of this Item. |
| clientModifiedDateUTC | DateTime? | client filesystem Modified Date of this Item. |
| expirationDays | Int32? | Message expiration days |
Returns: an Upload Specification element, containing the links for uploading, and the parameters for resume. The caller must know the protocol for sending the prepare, chunk and finish URLs returned in the spec; as well as negotiate the resume upload.
GET https://account.sf-api.com/sf/v3/Shares(id)/Redirection
Returns the redirection endpoint for this Share.
| id | String | Share identifier |
Returns: The Redirection endpoint Information
GET https://account.sf-api.com/sf/v3/Shares/Inbox
GET https://account.sf-api.com/sf/v3/Shares/Inbox(id)
Retrieve all outstanding Shares in the inbox.
| userId | String | User identifier |
| type | ShareType | Share type |
| archived | Boolean | Only get archived items |
Returns: List of Shares created by the authenticated user
GET https://account.sf-api.com/sf/v3/Shares(shareId)/Recipients(aliasId)/Message?asJson=false
Returns sent message content. By default the message is returned as a plain string. If asJson is true, the message string is wrapped in a Json object with a single "Message" property.
| shareId | String | Share identifier |
| aliasId | String | Share alias identifier |
| asJson | Boolean | Return data as JSON |
| includeExpired | Boolean | Specifies whether or not expired shares should be returned. Set to false by default |
Returns: Sent Message Content