Citrix ShareFile supports external integration through a simple HTTPS interface that accepts requests as part of a URL query
string and replies to requests with JSON or XML responses. This API documentation is targeted toward software engineers and
developers who seek to integrate access to a ShareFile account into other applications.
For assistance with API mechanics or other details, open a support ticket from the Help page of your ShareFile account or using
this contact form. Your request will be routed to
a member of our API integration/engineering team for further assistance.
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.
ShareFile API Concepts
This section attempts to address a number of questions about the structure of a ShareFile account in an FAQ-style format.
- What does a ShareFile account look like programmatically?
- A ShareFile account is presented as a virtual file system. Folders consist of items that may include files, folders and
rarely seldom-seen objects called notes and links. Paths to items within ShareFile are represented "Unix-style" by item
names separated by forward slashes and beginning with a single forward slash (example: /Path/To/MyFile.pdf).
- What is the relationship between users and accounts?
- Every unique ShareFile account represents an independent namespace and file system. An account exists at a specific
URL (for example, citrix.sharefile.com or acmecompany.sharefile.eu). The first part of an account’s URL is called the
subdomain. A user at a given email address (jane@example.com) can exist in two or more independent accounts and is
treated as two completely distinct users. Applications using the API always log in to a single account at any given
time.
- What are IDs?
- Every item in the ShareFile system (such as an account, file, folder, user, group, etc.) has a 36-character
immutable identifier in GUID format. These identifiers remain constant for the lifetime of an item. Renaming a
file or folder will not change its ID. Uploading a new version of a file creates a new object with a new ID.
- How do I upload or download a file?
- File transfers are usually performed against a server that is different from the primary API server. For an
upload, initiate a file/upload request and then POST the file to the provided URL. For downloads, initiate a
file/download request and GET the file from the provided URL. Note that the default format for uploads is as
part of a multipart/form POST, similar to how a web browser would submit a file to a server.
- What metadata exists for files?
- Files can have separate display and download names in the system, but these are usually the same (and it is
recommended to keep them the same.) Files have only one creation date and no modification date; modifying a file
is equivalent to creating a new file object with a new creation date. The ShareFile system computes the MD5 of
every file and provides it in directory listings.
- What metadata exists for folders?
- Folder metadata is similar to file metadata but also includes a file count of all enclosed files in that folder
and its children. Additionally, a field called progenyeditdate indicates the last timestamp that any changes (adds,
edits or deletes) were made in this folder or any of its children and can be used to quickly track changes within
a folder structure.
- What metadata exists for users?
- Users have a first name, last name, company name, and one or more email addresses registered in the system. One email
address is always considered primary and is used by default for email notifications.
- What timezone are datetimes returned in?
- Datetimes are returned in the time zone of the user who the API is acting on behalf of (as configured within the ShareFile
web application.) A timezone override can be specified during a single request by specifying tz=offset, where offset is a number
in minutes between -900 and 900 in relation to UTC. For example, tz=0 returns times in UTC, tz=-300 returns time in US Eastern
time, etc.
- What is ShareFile’s access control model?
- Access control is configured on a folder-by-folder basis. A folder’s access control list can contain one or more groups as
well as one or more individual users. If a user’s access to a folder is wholly on account of groups, a user’s effective
permissions consist of the most permissive set from the sum of their group memberships. If a user’s access to the folder is
based on an individual access grant, the individual permissions always override any group permissions. One exception is the
Super User Group; members of the Super User Group always have full permissions on every folder in the system.
ShareFile permissions consist of Download, Upload, Delete and Admin (which is the right to grant permissions to other users
on a given folder). Some ShareFile accounts have an additional View permission that is a subset of Download. Additionally,
users may have notifications enabled for either Upload or Download on a given folder.
- What rate limiting exists for the ShareFile API?
- Excessive usage of
the API will be curtailed programmatically. If you believe this will impact your application, please contact us for further
information.
- Are there other ways to integrate with ShareFile?
- Yes. Some legacy applications may be better suited to using the FTP protocol; ShareFile provides an FTP-compatible layer
for accessing an account. ShareFile also offers a power tool called SFCLI, the ShareFile Command Line Interface, which operates
as a copy command that can transfer files to or from ShareFile from a batch file or other script. Download SFCLI from
within your account on the Apps tab.
- Can I get an account for testing?
- Yes, complimentary/demo accounts are available to ISVs who are seeking to integrate ShareFile support into their applications.
Please contact us using the link at the top of this page and describe your application and proposed integration.