ShareFile allows you to create a custom-branded, password-protected space where you can exchange business files with clients easily and securely. Whether you need to send large files by email, conduct a secure file transfer or set up a collaboration space where project-related files can be posted, ShareFile has the solution for you. Sign up for a free trial of ShareFile

HTTPS API Documentation

Outlined here in detail is a extensive look at the operations and parameters that can be used to communicate with the ShareFile API.

Code Samples

One of the most useful ways to learn about the ShareFile API is through one of these code samples. They are provided for reference purposes only, and no representation is made as to their suitability, security or reliability for any purpose. However, you are free to adapt this code to use in your own projects. Refer to the license attribution at the top of each file for more information.

C# (.NET)
(18 KB)
Java
(16 KB)
PHP
(12 KB)
Python
(11 KB)
Ruby
(10 KB)
VB.NET
(20 KB)

Definitions

The following symbols in angle brackets are used to specify data types for parameters in this documentation. These specifiers SHOULD NOT be included in a live API request. Including items such as <b> will cause an error.

Data Types:

  • <b> - Represents a Boolean object (the words true, false, 0 or 1)
  • <s> - Represents a String object
  • <i> - Represents a 32-bit integer written as a decimal string
  • <l> - Represents a List of objects

Request

API methods are URLs called over the HTTPS protocol, specifically of the form:

      https://subdomain.sharefile.com/rest/method.aspx?[parameter collection]

All API calls should be sent as a GET HTTP request. The ShareFile system supports a number of domains besides sharefile.com; use the same address used to log in to the web application to call the API.

Response

Responses are returned in one of two formats based on the caller's preference.

  • JSON can be returned by appending &fmt=json to the query string
    Alternatively, JSONP can be returned by appending &fmt=jsonp along with an optional callback: &jsonp_callback=callbackname
  • XML can be returned by appending &fmt=xml to the query string

Note: Failure to specify a fmt will return a deprecated plain-text format that is no longer supported.

Example Responses

JSON (&fmt=json) XML (&fmt=xml)
{ "error" : false, "value" : "abcdef123456" } <ShareFileResponse><error>false</error><value>abcdef12356</value></ShareFileResponse>
{ "error" : true, "errorMesssage" : "Invalid authid. Please log in again." } <ShareFileResponse><error>true</error><errorMessage>abcdef12356</errorMessage></ShareFileResponse>

Authentication

NEW: OAuth2 authentication is available. Please contact us to be issued an OAuth API key. OAuth2 can be used as a mechanism for retrieving shorter-lived authid's without handling a user's credentials. See the OAuth2 Getting Started Guide for more information.

For simpler authentication, before calling any API methods, the caller must retrieve an authid from ShareFile.

Authentication URL example:
https://subdomain.sharefile.com/rest/getAuthID.aspx?op=login&fmt=json&username=email@address&password=password

Response: The authentication URL will return among its results an authid that MUST be used for all subsequent API calls in the current session. (ex. 0oye2k45kbna1234abcd1gyk) The duration of an authid is eighteen (18) hours. API callers must renew authentication within that period to continue using the API.

RECOMMENDED: For security purposes, authentication can be performed via an HTTPS POST of the "username" and "password" through the HTTP Headers as individual headers instead of on the query string.

POST https://subdomain.sharefile.com/rest/getAuthID.aspx HTTP/1.1
Content-Type: application/x-www-form-urlencoded
password: yourpassword
username: email@example.com
Host: subdomain.sharefile.com
Connection: Keep-Alive

General API Methods

For each object in ShareFile that the API consumes, a different page is responsible for those operations which are listed below. If a method operation takes an item name as a parameter, the supplied name should not include invalid naming characters.

Method URL
folder https://subdomain.sharefile.com/rest/folder.aspx
file https://subdomain.sharefile.com/rest/file.aspx
users https://subdomain.sharefile.com/rest/users.aspx
group https://subdomain.sharefile.com/rest/group.aspx
search https://subdomain.sharefile.com/rest/search.aspx

Detailed method operators are outlined below. Method calls have a minimum of three (3) required parameters unless noted; otherwise an error will be thrown and the API call will not complete with the intended results. The three (3) required parameters are:

  1. op - This is the operator parameter to tell ShareFile what action you want to perform.
  2. authid - Allows ShareFile to communicate with your application securely.
  3. id - The identifier of the folder, file or user to perform the action (op) against.

Method: folder

https://subdomain.sharefile.com/rest/folder.aspx?op=
Operator (op=) Description Required Parameters Optional Parameters(Default)
breadcrumbs Returns ids and names for a folder's complete path. authid<s>
id<s> or path<s>
copy Recursively copies a folder to another location. authid<s>
id<s> or path<s>
destid<s> or destpath<s>
create Creates a folder. authid<s>
id<s> or path<s>
name<s>
overwrite<b> (true)
details<s>
delete Recursively deletes a folder. authid<s>
id<s> or path<s>
delete-custom-metadata Deletes the single Metadata entry with the given name for the folder specified by id or path. Metadata entries are custom name/value pairs that are associated with a File or Folder. authid<s>
id<s> or path<s>
name<s>
edit Updates a folder's name or details. authid<s>
id<s> or path<s>
name<s>
details<s>
get Returns basic metadata for the requested folder. authid<s>
id<s> or path<s>
getex Returns all metadata for the requested folder. authid<s>
id<s> or path<s>
extended<b> (false)
getacl Returns a permission list for the given folder including distribution groups. authid<s>
id<s> or path<s>
geteffacl Returns a permission list for the given folder without distribution groups. authid<s>
id<s> or path<s>
get-custom-metadata Gets the single Metadata entry with the given name for the folder specified by id or path. Metadata entries are custom name/value pairs that are associated with a File or Folder. authid<s>
id<s> or path<s> name<s>
grant Grants folder privileges to the specified user. authid<s>
id<s> or path<s>
userid<s> or email<s>
download<b> (true)
upload<b> (false)
view<b> (true)
admin<b> (false)
delete<b> (false)
notifyupload<b> (false)
notifydownload<b> (false)
recursive<b> (false)
get<b> (false)
notifyaddeduser<b> (false)
grantgroup Grants folder privileges to the specified group. authid<s>
id<s> or path<s>
groupid<s>
download<b> (true)
upload<b> (false)
view<b> (true)
admin<b> (false)
delete<b> (false)
notifyupload<b> (false)
notifydownload<b> (false)
recursive<b> (false)
get<b> (false)
notifyaddeduser<b> (false)
list Returns a list of files and subfolders in the requested folder. Use id=/ or id=root for the account root. To get the authenticated user's home or shared folders use id=home or id=allshared, respectively. authid<s>
id<s> or path<s>
versions<b> (false)
listex Returns a list of files and subfolders with additional information in the requested folder. See above op=list for special folder ids. authid<s>
id<s> or path<s>
versions<b> (false)
move Recursively moves a folder. authid<s>
id<s> or path<s>
destid<s> or destpath<s>
request Delivers a Request a File email to the specified recipient. authid<s>
id<s> or path<s>
to<s>
subject<s>
body<s>
ccSender<b> (false)
requireLogin<b> (false)
expirationDays<i> (30)
notifyOnUpload<b> (false)
request-url Returns a Request a File link to the specified folder. authid<s>
id<s> or path<s>
requireUserInfo<b> (false)
expirationDays<i> (30)
notifyOnUpload<b> (false)
revoke Revokes folder privileges from the specified user. authid<s>
id<s> or path<s>
userid<s> or email<s>
revokegroup Revokes folder privileges from the specified group. authid<s>
id<s> or path<s>
groupid<s>
send Delivers a Send a File email for the specified folder. authid<s>
id<s> or path<s>
to<s>
subject<s>
body<s>
ccSender<b> (false)
requireLogin<b> (false)
anonLink<b> (false)
expirationDays<i> (30)
notifyOnDownload<b> (false)
isViewOnly<b> (false)
maxDownloads<i> (unlimited)
send-url Return a Send a File link. authid<s>
id<s> or path<s>
requireUserInfo<b> (false)
expirationDays<i> (30)
notifyOnDownload<b> (false)
maxDownloads<i> (unlimited)
set-custom-metadata Sets the single Metadata entry with the given name for the folder specified by id or path. Metadata entries are custom name/value pairs that are associated with a File or Folder. authid<s>
id<s> or path<s> name<s>
value<s>

Method: file

https://subdomain.sharefile.com/rest/file.aspx?op=
Operator (op=) Description Required Parameters Optional Parameters (default)
copy Copies the specified file to another folder authid<s>
id<s> or path<s>
destid<s> or destpath<s>
createnote Adds a note to the specified parent folder authid<s>
description<s>
parentid<s>
sendnotifications<b> (false)
createurl Adds a URL to the specified parent folder. authid<s>
link<s>
parentid<s>
sendnotifications<b> (false)
delete Deletes the specified file. authid<s>
id<s> or path<s>
singleversion<s> (false)
delete-custom-metadata Deletes the single Metadata entry with the given name for the file specified by id or path. Metadata entries are custom name/value pairs that are associated with a File or Folder. authid<s>
id<s> or path<s>
name<s>
directdl Initiates a download of the specified file. authid<s>
id<s>
download Returns a direct link to download the specified file. authid<s>
id<s>
edit Edits the file attributes. authid<s>
id<s>
name<s>
details<s>
singeversion<b> (false)
get Returns metadata for the requested file. authid<s>
id<s> or path<s>
getex Returns additional metadata for the requested file. authid<s>
id<s> or path<s>
versions<b> (false)
get-custom-metadata Gets the single Metadata entry with the given name for the file specified by id or path. Metadata entries are custom name/value pairs that are associated with a File or Folder. authid<s>
id<s> or path<s> name<s>
move Moves the specified file to another folder. authid<s>
id<s> or path<s>
destid<s> or destpath<s>
send Sends a Send a File email to the specified recipient. Set useStreamIDs to true to keep the Share URL current with the most recent version of the shared file. authid<s>
id<s> or path<s>
to<s>
subject<s>
body<s>
ccSender<b> (false)
requireLogin<b> (false)
anonLink<b> (false)
expirationDays<i> (30)
notifyOnDownload<b> (false)
isViewOnly<b> (false)
maxDownloads<i> (unlimited)
useStreamIDs<b> (false)
send-url Returns a Send a File URL for the specified file to be downloaded. Set useStreamIDs to true to keep the Share URL current with the most recent version of the shared file. authid<s>
id<s> or path<s>
requireUserInfo<b> (false)
expirationDays<i> (30)
notifyOnDownload<b> (false)
maxDownloads<i> (unlimited) useStreamIDs<b> (false)
set-custom-metadata Sets the single Metadata entry with the given name for the file specified by id or path. Metadata entries are custom name/value pairs that are associated with a File or Folder. authid<s>
id<s> or path<s> name<s>
value<s>
upload Generates a URL to which a file can be uploaded via a multipart/form-data POST using the field name File1. Additional upload information. authid<s>
filename<s>
folderid<s> (filebox)
unzip<b> (false)
overwrite<b> (false)
details<s>
title<s>

Method: users

https://subdomain.sharefile.com/rest/users.aspx?op=
Operator (op=) Description Required Parameters Optional Parameters (default)
create Create a ShareFile user either as a client or employee with the specified permissions. Using the confirm parameter, a confirmed user that will not need to verify personal information and password upon their initial login, can be created. authid<s>
firstname<s>
lastname<s>
email<s>
isemployee<b>
company<s>
isadmin<b> (false)
createfolders<b> (false)
usefilebox<b> (false)
manageusers<b> (false)
password<s>
notify<b> (false)
canresetpassword<b> (true)
canviewmysettings<b> (true)
addshared<b> (false)
confirm<b> (false)
delete Deletes a user completely from the account, and optionally reassigns items to another user. Note: this operation may take several minutes depending on the number of associated files for this user authid<s>
id<s>
reassignid<s>
deletef Deletes a user from all folders, but not from the account, and optionally reassigns items to another user. Note: this operation may take several minutes depending on the number of associated files for this user authid<s>
id<s>
reassignid<s>
edit Updates the specified user with the provided information authid<s>
id<s>
firstname<s>
lastname<s>
email<s>
company<s>
get Returns information about the specified user. Note: id may be a user id or email address authid<s>
id<s>
getex Returns additional information about the specified user. Note: id may be a user id or email address authid<s>
id<s>
getaddressbook Returns an address book (shared, personal, group) for the current user authid<s>
type<s> (all)
getfavoritefolders Returns current user's favorite folders authid<s>
listc Returns a list of all clients in the account authid<s>
liste Returns a list of all employees in the account authid<s>
removefavoritefolder Remove a folder from the current user's favorite list authid<s>
id<s>
resendwelcome Resend the email welcome message to the specified user authid<s>
id<s>
resetp Resets the current or specified user's password. To change the current user's password, specify oldp and newp. As an administrative user, to reset another user's password, specify newp and the id of the user whose password should be changed. authid<s>
newp<s>
id<s> or oldp<s>
setfavoritefolder Adds the specified folder to the current user's favorite list. authid<s>
id<s>

Method: group

https://subdomain.sharefile.com/rest/group.aspx?op=
Operator (op=) Description Required Parameters Optional Parameters (default)
addcontacts Adds a single user or comma separated list of users to a distribution group. Users can be either an id or email address. authid<s>
id<s>
contacts<l>
create Creates a distribution group and optionally adds a user or list of users to the newly created group. authid<s>
name<s>
isshared<b> (false)
contacts<l>
delete Deletes the specified group. authid<s>
id<s>
get Returns the specified group. authid<s>
id<s>
getex Returns the specified group with a list of associated users. authid<s>
id<s>
list Returns a list of all distribution groups. authid<s>
removecontacts Removes a user or comma separated list of users from the specified distribution group. Users can be either an id or email address. authid<s>
id<s>
contacts<l>
update Updates the specified information of the distribution group. authid<s>
id<s>
name<s>
isshared<b>

Method: search

https://subdomain.sharefile.com/rest/search.aspx?op=
Operator (op=) Description Required Parameters Optional Parameters (default)
search Returns a result set of files and folders that match the criteria of the "query" parameter. authid<s>
query<s>
showpartial<b> (false)

Additional File Upload Information

Multipart/Form-Data Upload
Multipart/Form-Data file uploads should follow the standard multipart/form-data request format. Notably the request header will need to set
Content-Type: multipart/form-data; boundary=
Content-Length:
In the request body part the following headers need to be set and proper boundaries and whitespace conventions need to be observed. While many HTTP libraries provide methods or functions to setup multipart/form-data, you can see an example of how to create this data manually in the c# and Java sample code.
Content-Disposition: form-data; name="File1"; filename="MyFile.name"
Content-Type:
Alternative to Multipart/Form-Data
Files may be uploaded by issuing a POST request containing raw file contents, rather than using multipart/form-data, by setting
Content-Type: application/octet-stream
and appending the following additional parameters to the storage center URL that was returned from the request to file.aspx?op=upload
  • raw=1 - the file bytes will be POSTed without any formatting in the request body.
  • filename=file.name - upload clients should inspect the storage center URL and add the filename parameter only if it is not already present. The presence of the filename parameter depends upon the Storage Zone location of the upload folder. When the zoneid of the folder is null, the filename will not be present in the returned storage center URL and clients will therefore need to append the filename parameter. Conversely when the zoneid has a value, the filename parameter will already be present, and should not be added by the upload client.
    • ex 1:
      The following URL is returned from file.aspx?op=upload:
      https://storage-ec2-1.sharefile.com/upload.aspx?uploadid=api-1111&batchid=123456&uploadtool=API&filename=TestFile1.txt&encparams=alsdflkjhsdf....ewriuywer
      Since the filename is already present, upload clients need only append the raw=1 parameter to perform a raw upload.
    • ex 2:
      The following URL is returned from file.aspx?op=upload:
      https://storage-ec2-1.sharefile.com/upload.aspx?uploadid=api-2222&batchid=98765&uploadtool=API&encparams=alsdflkjhsdf....ewriuywer
      Since the URL does not contain the filename parameter, upload clients need to append the raw=1&filename=file.name parameters to perform a raw upload.
Upload Response
The default response to a successul upload is a simple "OK". If you require additional information about the newly created file such as the id or md5 checksum, you can append &fmt=json to the storage center URL that was returned from the request to file.aspx?op=upload.
Batch Uploads
If you are uploading multiple files and have users on the folder with real-time upload notifications turned on, they will receive a notification for each file that you upload. To avoid this, and to send a consolidated notification for the batch of files you upload, you can append the following additional parameters to the storage center URL that was returned from the request to file.aspx?op=upload.
  • &isbatch=true&isbatchlast=false to indicate a file that is a part of an upload batch
  • &isbatch=true&isbatchlast=true to indicate a file that is the last file in an upload batch. This will trigger the notification.

Item Name/Title Format

API requests involving creation or editing of item names or titles, such as op=create in folder.aspx, are expected to supply valid names. A name containing invalid characters will be sanitized, and if the sanitized version of the name is not empty, the operation will proceed. To ensure cross-platform compatibility, characters such as " (double quote) that are valid in some operating systems but not others are not permitted in filenames in ShareFile.

Invalid Characters for File or Folder Names
  • \
  • /
  • :
  • *
  • ?
  • "
  • <
  • >
  • |
  • Names ending in "." without an extension
  • Leading or trailing whitespace