XML-API

General concepts

The API accepts valid XML sent over HTTP with the POST method to: /cgi-bin/xmlapi.cgi.

UTF-8 encoding is compulsory. Other character sets are not supported. The API is object-oriented. It allows to manipulate several types of objects, including users, groups, files and recipients. Some object properties are read-only, usually because their values are set at creation time.

Each API request may perform one operation only. Each API request must include a Set-Cookie header that specifies a valid FTAUser cookie, as provided at login time. Authentication is beyond the scope of the API but may still be performed automatically, as described in the appendix. All dates follow the XML Schema dateTime format. In requests, they must be expressed in the server’s local time. In responses, they are expressed in GMT.

Requests

Requests must follow this format :

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>files</dataType>
<operationType>fetch</operationType>
...
<data>
<transferId>a392af8b-a296-4442-a5d1-2b414502697f</transferId>
...
</data>
</request>

The XML elements request, dataType, operationType and data are compulsory. Depending on operationType, other elements may be required inside the request block, while the content of the data block depends on dataType. Refer to the documentation of each data type below for specifics.

Responses

On Success

On success, responses are in this format:

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>0</status>
...
<data>
<record>
<id>a392af8b-a296-4442-a5d1-2b414502697f</id>
...
</record>
</data>
<failureCount>0</failureCount>
</response>

On Error

Whenever an error occurs, the API responds with a status other than 0, and an errorMessage on each request field that caused the error, as follows:

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>-1</status>
<errors>
<emailAddresses>
<errorMessage>This field is invalid</errorMessage>
</emailAddresses>
</errors>
</response>

Other elements may appear in the response block depending on the request’s operationType. Likewise, the contents of the record block depend on the request’s dataType. Each record block always includes an id element that specifies the object’s unique identifier. Sometimes a count of failes is added (e.g. response on adding users).

Request Operation Types

Fetch

Fetch requests are used to retrieve a list of objects of a particular type. The elements startRow and endRow specify the start and end indexes, default to 0 and 100 respectively. Depending on dataType, one or more filter may be specified in the data block, for instance:

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>files</dataType>
<operationType>fetch</operationType>
<startRow>0</startRow>
<endRow>10</endRow>
<data>
<transferId>a392af8b-a296-4442-a5d1-2b414502697f</transferId>
...
</data>
</request>

startRow and endRow are repeated in responses, but may have lower values than in the request, depending on the number of rows available, as indicated by the element totalRows.

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>0</status>
<startRow>0</startRow>
<endRow>3</endRow>
<totalRows>3</totalRows>
<data>
<record>
...
</record>
</data>
</response>

Add

Add requests create one new object at a time. They do not include any additional element in the request block. All required properties for the given dataType should be made available in the data block. Callers need not specify an id for the new object, one is automatically generated.

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>users</dataType>
<operationType>add</operationType>
<data>
...
</data>
</request>

Responses typically repeat the same elements found in the request’s data block inside a record block. In some cases, only its identifiers (including but not limited to id) may be returned. Note that some object types may not be created by the API.

Update

Update requests modify as many properties as necessary on one object only. No additional element is required in the request block. They are similar to add requests, except that the object’s id is compulsory.

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>users</dataType>
<operationType>update</operationType>
<data>
<id>b588bba4-f067-11df-8e90-00248c819310</id>
...
</data>
</request>

Responses typically repeat the same elements found in the request’s data block inside a record block. In some cases, only its identifiers (including but not limited to id) may be returned. Note that some object types may not be updated by the API.

Remove

Remove requests remove objects altogether. No additional element is required in the request block. Only the object’s identifiers are compulsory.

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>groups</dataType>
<operationType>remove</operationType>
<data>
<id>fa73cb14-f067-11df-9f18-00248c819310</id>
</data>
</request>

In responses, the record block only includes the object’s id. Note that some object types may not be removed by the API.

Import

Import request are transmitting the contents of a file. Additionally the file element is required inside the data block. All required properties for the given dataType should be made available in the data block.

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>contactcsvimport</dataType>
<operationType>import</operationType>
<data>
<file>EMAILADDRESS,DISPLAYNAME,TITLE,LASTNAME,FIRSTNAME ...</file>
...
</data>
</request>

The response defines the dataType. Typically it is the id where the filecontent was imported.

info

• Currently only the ContactsCsvImport dataType supports the import operationType.

Administration Data Types

In order to add, update or remove these data types, the FTAUser cookie should be one that’s been provided for a Company Administrator login. If it was provided for a user login, only objects that directly relate to that user may be fetched.

Groups

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

Fetch requests may include one of these filter elements:

• groupId set to a group’s identifier, will retrieve only this specific group.
• memberId set to a group or a user’s identifier, will retrieve only the group that has this member.

With no filter, a fetch will return the same groups as shown to the Company Administrator in the System > Groups tab. Users may request for the properties of the group they belong to by setting memberId to their user identifier.

<record>
<id>eee59ae5-55e9-4e39-a0da-e4ebe1f44027</id>
<groupName>AD Users</groupName>
<hierarchy/>
<canInvite>true</canInvite>
<canSign>false</canSign>
<canSendNewsletters>true</canSendNewsletters>
<canSendTeamTransfers>true</canSendTeamTransfers>
<canSendAs>true</canSendAs>
<sendAsAddresses/>
<teamMemberAddresses/>
<storageQuotaUnit>GBYTE</storageQuotaUnit>
<storageQuota>10</storageQuota>
<userStorageQuotaUnit>GBYTE</userStorageQuotaUnit>
<userStorageQuota>10</userStorageQuota>
<usedStorageMB>0</usedStorageMB>
<usedStorage>0b</usedStorage>
<authServer>0-LOCAL-AUTH</authServer>
<transfersCount>50</transfersCount>
<accessRanges>192.168.1.0/255.255.255.0</accessRanges>
<hasAccessRanges>true</hasAccessRanges>
<positiveSignUpRules>*mycompany.com</positiveSignUpRules>
<negativeSignUpRules>*sales.mycompany.com</negativeSignUpRules>
<hasSignUpRules>true</hasSignUpRules>
<externalOnly>false</externalOnly>
<closeToLimits>false</closeToLimits>
</record>

The primary Company Administrator may set auditors to a list of Administrators’ identifiers. These Administrators will then become Group Administrators authServer should be set to an empty string at creation time, and treated as an opaque property subsequently.

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID			Req	Req
groupId	UUID	Opt
memberId	UUID	Opt
groupName	String		Req	Req
hierarchy	String		Opt	Opt
canInvite	Boolean		Req	Req
canSign	Boolean		Req	Req
canSendNewsletters	Boolean		Req	Req
canSendTeamTransfers	Boolean		Req	Req
canSendAs	Boolean		Req	Req
sendAsAddresses	List of strings		Req	Req
teamMemberAddresses	List of strings		Req	Req
storagequota Unittest	Enum "GBYTE", "MBYTE" or "KBYTE"		Optl	Opt
storageQuota	Unsigned integer		Opt	Opt
userStorageQuotaUnit userStorageQuota	GBYTE|MBYTE|KBYTE, Unsigned integer		Optl	Opt
usedStorageMB (in Megabytes)	Unsigned integer		Opt	Opt
usedStorage	Size as string
authServer	UUID		Opt	Opt
transfersCount	Unsigned integer		Opt	Opt
accessRanges	List of IPv4 addresses/ranges		Opt	Opt
hasAccess-Ranges	Boolean		Opt	Opt
positiveSignUp-Rules	List of patterns		Opt	Opt
negativeSignUp Rules	List of patterns		Opt	Opt
hasSignUpRules	Boolean		Optl	Opt
externalOnly	Boolean		Optl	Opt
closeToLimits	Boolean		Optl	Opt

Users

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

Fetch requests may include one of these filter elements :

• userId set to a user’s identifier, will retrieve only this specific user.
• currentUserOnly set to true, will retrieve only the current user.
• auditorsOnly set to true, will restrict the output to Company Administrators. Users may request for their own properties by setting currentUserOnly to true

<record>
<id>b8eca3c6-7d24-499d-8e2a-d8a90150292c</id>
<userName>some.one@mailinator.com</userName>
<realName>Some One</realName>
<emailAddress>some.one@mailinator.com</emailAddress>
<authType>LOCAL</authType>
<role>USER</role>
<groupName>interne</groupName>
<assignedGroupName/>
<lastLoginDate>2019-03-20T09:25:09</lastLoginDate>
<secondLastLoginDate>2019-03-18T14:35:27</secondLastLoginDate>
<firstLogin>false</firstLogin>
<isLoggedIn>true</isLoggedIn>
<hasSession>true</hasSession>
<sessionDelay/>
<lastPasswordChangeDate>2019-02-26T15:48:44</lastPasswordChangeDate>
<disabledUser>false</disabledUser>
<disabledUserReason/>
<readOnly>false</readOnly>
<setPassword>false</setPassword>
<newPassword/>
<newPasswordAgain/>
<storageQuotaUnit>GBYTE</storageQuotaUnit>
<storageQuota>10</storageQuota>
<hasExpiryDate>false</hasExpiryDate>
<expiryDate>2020-03-19T09:25:10</expiryDate>
<transfersCount>0</transfersCount>
<transferFilesSize>16.7kB</transferFilesSize>
<savedStorageSize>6.3kB</savedStorageSize>
<archiveFilesSize>0B</archiveFilesSize>
<deletedFilesSize>0B</deletedFilesSize>
<usedStorageMB>0.010431</usedStorageMB>
<usedStorage>10.4kB</usedStorage>
<storageLeft>9999989569</storageLeft>
<storageLeftString>9.9GB</storageLeftString>
<accessRanges/>
<hasAccessRanges>false</hasAccessRanges>
<closeToLimits>false</closeToLimits>
<miscFlags>NEWSLETTERS,TEAMTRANSFERS,SMARTDELIVERY,REPORTS,LICENSED,</miscFlags>
<isNoticeBoardEnabled>false</isNoticeBoardEnabled>
<noticeBoardMessage/>
<showUploadManagerWarning>true</showUploadManagerWarning>
</record>

authType should always be set to LOCAL, and userName match emailAddress.

• role knows three valid values : LIMITED for external recipients, USER for users and AUDITOR for Company Administrators.
• storageQuotaUnit can be KBYTE, MBYTE or GBYTE.
• miscFlags should be set to an empty string at creation time, and treated as an opaque property subsequently. At creation time, emailAddresses replaces the userName, realName and emailAddress elements and allows creating several users in one call. For instance:

<emailAddresses>Some One &lt;some.one@mailinator.com&gt;, Some Body
&lt;some.body@mailinator.com&gt;,... </emailAddresses>

Keyword	Type	Fetch	Add	Update	Remove
id	UUID			Req	Req
userName	String	Opt		Req
realName	String			Opt
emailAddress	String		Req	Req
authType	Enum LOCAL|LDAP		Req
role	Enum LIMITED|USER|AUDITOR	Opt	Req	Req
groupName	String	Opt	Opt
assignedGroupName	String
lastLoginDate	Date
secondLastLoginDate	Date
firstLogin	Boolean
isLoggedIn	Boolean
hasSession	Boolean
sessionDelay	Integer
lastPasswordChangeDate	Date
disabledUser	Boolean	Opt	Opt	Opt
disabledUserReason	String	Opt	Opt	Opt
readOnly	Boolean
setPassword	Boolean			Opt
newPassword	String			Opt
newPasswordAgain	String			Opt
storageQuotaUnit	String	Opt	Req	Opt
storageQuota	Integer	Opt	Req	Opt
hasExpiryDate	Boolean		Req	Req
expiryDate	Date		Opt	Opt
transfersCount	Integer
transferFilesSize	Size as string
savedStorageSize	Size as string
archiveFilesSize	Size as string
deletedFileSize	Size as string
usedStorageMB	Size as string
usedStorage	Size as string
storageLeftString	Size as string
accessRanges	String
hasAccessRanges	Boolean
newCount	Integer
closeToLimits	Boolean
miscFlags	List
isNoticeBoardEnabled	Boolean
noticeBoardMessage	String
showUploadManagerWarning	Boolean
preferredLanguage	String		Req
bccPassword	Boolean		Opt
currentUserOnly	Boolean	Opt
auditorsOnly	Boolean	Opt
userId	String	Opt

Audit entries

Fetch	Update	Add	Remove
Yes	No	No	No

Fetch requests may include one of these filter elements to restrict the output :

• idFilter set to the identifier of any object.
• typeFilter set to one of ALL (default), USER, GROUP, TRANSFER or INVITE.
• fileNameFilter set to a complete filename or part of it. In addition, fileTypeFilter may be set to a MIME type to restrict output to, for example text/plain

Additional filters may be applied to any of the above:

• minDateFilter and maxDateFilter for date filtering. If these are unset, the output will default to the past 7 days.
• userFilter for user filtering when set to a user’s identifier.

Failed and successful events may be filtered with successFilter set to ALL (default), FAILURE or SUCCESS. This is without effect when fileNameFilter is set. To request for a specific transfer or invite, set idFilter to that object’s identifier.

<record>
<id>0bddac11-7a4a-4e78-8126-22033f1c4435</id>
<actionType>LOGIN</actionType>
<resultCode>0</resultCode>
<userId>4aa30a22-21c2-4e71-a0e1-5bc2e615ef29</userId>
<userName>some.one@mailinator.com</userName>
<objectType>USER</objectType>
<objectId>4aa30a22-21c2-4e71-a0e1-5bc2e615ef29</objectId>
<objectValue>some.one@mailinator.com</objectValue>
<parentObjectType>NA</parentObjectType>
<parentObjectId></parentObjectId>
<parentObjectValue></parentObjectValue>
<actionDate>2010-11-22T02:30:02</actionDate>
<formattedValue>Logged in</formattedValue>
<address>::1</address>
<port>42517</port>
<removed>false</removed>
</record>

• A negative resultCode indicates a failure. If the object type is EMAIL, it maps to the SMTP status code.
• actionType is one of ADD, UPDATE, FETCH, DOWNLOAD, UPLOAD, DROP, REMOVE, LOGIN, LOGOUT, SEND or FORGET.
• objectType and parentObjectType are one of NA, USER, PASSWORD, CONTACT, INVITE, TRANSFER, TRANSFERFILE, RECIPIENT, COMMENT, POLICY or EMAIL.

Keyword	Type	Fetch	Add	Update	Remove
id	UUID		N/A	N/A	N/A
idFilter	UUID	Opt
typeFilter	String	Opt
userFilter	UUID	Opt
fileNameFilter	String	Opt
fileTypeFilter	String	Opt
successFilter	Enum "ALL"(default), "FAILURE" or "SUCCESS"	Opt
actionType	String
resultCode	Integer
userId	UUID
userName	String
objectType	String
objectId	UUID
objectValue	String
parentObjectType	String
parentObjectId	UUID
parentObjectValue	String
actionDate	Date
formattedValue	String
address	IP address
port	Integer
removed	Boolean

Settings entries

Fetch	Update	Add	Remove
Yes	No	Yes	No

Fetch requests have to include this filters:

• objectId set to the identifier of any object.
• objectType set to USER or GROUP.

<record>
<id>b8eca3c6-7d24-499d-8e2a-d8a90150292c</id>
<objectType>USER</objectType>
<maxCount>10</maxCount>
<maxCountInt>10</maxCountInt>
<maxCountOverride>0</maxCountOverride>
<daysToExpiry>30</daysToExpiry>
<daysToExpiryInt>30</daysToExpiryInt>
<daysToExpiryOverride>0</daysToExpiryOverride>
<checkPasswords>YES</checkPasswords>
<checkPasswordsOverride>false</checkPasswordsOverride>
<confirmNotifications>YES</confirmNotifications>
<confirmNotificationsOverride>false</confirmNotificationsOverride>
<recipientReminders>YES</recipientReminders>
<recipientRemindersOverride>false</recipientRemindersOverride>
<recipientNotifications>YES</recipientNotifications>
<recipientNotificationsOverride>true</recipientNotificationsOverride>
<downloadNotifications>YES</downloadNotifications>
<downloadNotificationsOverride>false</downloadNotificationsOverride>
<expiryReminders>NO</expiryReminders>
<expiryRemindersOverride>false</expiryRemindersOverride>
<signFiles>false</signFiles>
<uploadApplet>YES</uploadApplet>
<downloadApplet>YES</downloadApplet>
<isPincodeRequired>Yes</isPincodeRequired>
<pincodeOverride>true</pincodeOverride>
<expiredNotCompletedNotifications>NO</expiredNotCompletedNotifications>
<appletsOverride>false</appletsOverride>
<fileNames/>
<mobileNumber/>
<preferredLanguage>de</preferredLanguage>
<signature/>
</record>

Keyword	Type	Fetch	Add	Update	Remove
id	UUID			Req
objectId	UUID	Req
objectType	String	Req		Req
maxCount	USER|Integer			CR
maxCountInt	Integer
maxCountOverride	Integer
daysToExpiry	USER|Integer			CR
daysToExpiryInt	Integer
daysToExpiryOverride	Integer
checkPasswords	USER|YES|NO			CR
checkPasswordsOverride	Boolean
confirmNotifications	USER|YES|NO			C1
confirmNotificationsOverride	Boolean
recipientReminders	USER|YES|NO			C1
recipientRemindersOverride	Boolean
recipientNotifications	USER|YES|NO			C1
recipientNotificationsOverride	Boolean
downloadNotifications	USER|YES|NO			C1
downloadNotificationsOverride	Boolean
expiryReminders	USER|YES|NO			C1
expiryRemindersOverride	Boolean
signFiles	Boolean			CR
uploadApplet	USER|YES|NO			C1
downloadApplet	YES|NO
isPincodeRequired	USER|Yes|No			C1
pincodeOverride	Boolean
expiredNotCompletedNotifications	USER|YES|NO			C1
appletsOverride	Boolean
fileNames	String			C1
mobileNumber	String			O1
preferredLanguage	String			O1
signature	String			O1
uploadSettingsOnly	Boolean			Opt
emailSettingsOnly	Boolean			Opt

tip

• If uploadSettingsOnly is set on update all settings marked with C1 are required and settings marked with O1 are optional.
• If emailSettingsOnly is not set on update all settings marked with CR are required, otherwise they are omitted.

Policy conditions

This request may be used by Company Administrator or by users. Users are only able to fetch policies affecting them.

Fetch	Update	Add	Remove
Yes	No	No	No

<response>
    <status>0</status>
    <startRow>0</startRow>
    <endRow>1</endRow>
    <totalRows>1</totalRows><data>
        <record>
            <id>3d7b4e80-32db-4454-af34-c0cc416dc430</id>
            <condType>FILESIZE</condType>
            <operatorName>LESS</operatorName>
            <value>2GB</value>
        </record>
    </data>
</response>

Keyword	Type/Value	Fetch
id	UUID	req
objectId	String	req
objectType	"USER"	req
newPassword	String
newPasswordAgain	String

User Data Types

These data types may be added, updated or removed if the FTAUser cookie is for a user login. Company Administrators may only perform fetch requests.

Invites

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

Fetch requests may include one of these filter elements:

• inviteId set to an invite’s identifier, will retrieve only this specific invite.
• box knows three valid values: OUTBOX (default) for sent invites, INBOX for received invites or REVIEWBOX. The latter is only valid for Company Administrators.

<record>
<id>1f0d93d1-4e73-4e38-9d42-c3de42ddde4f</id>
<subject>Upload big files here</subject>
<message>You can upload big files here. Thanks.</message>
<creator>some.one@mailinator.com</creator>
<editable>true</editable>
<appendable>true</appendable>
<removable>true</removable>
<hasErrors>false</hasErrors>
<recipients>some.body@mailinator.com</recipients>
<completion>100%</completion>
<creationDate>2010-03-18T07:49:46</creationDate>
<deliveryDate>2010-03-18T07:49:46</deliveryDate>
<expiryDate>2010-12-25T15:59:59</expiryDate>
<inviteStatus>ACTIVE</inviteStatus>
<onHold>false</onHold>
<archiveId/>
</record>

tip

If inviteStatus is set to UNDERREVIEW, Company Administrators may set it to REVIEWED or REJECTED to respectively allow or block the invite.

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID			Req	Req
inviteId	UUID	Opt
box	Enum "OUTBOX" (default) "INBOX" or "REVIEWBOX"	Opt
subject	String		Req
message	String		Req
creator (not editable)	Email Address			Req
editable	Boolean
appendable	Boolean
removable	Boolean
hasErrors	Boolean
recipients	List of Email Addresses		Req
completion	Percentage
creationDate	Date
deliveryDate	Date		Req
expiryDate	Date		Req	Req
inviteStatus	Enum "UNDERREVIEW", "ACTIVE", "ONHOLD" or "EXPIRED"			Opt
onHold	Boolean			Req
archiveId	UUID	Opt

Transfers

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

Fetch requests may include one of these filter elements:

• transferId set to a transfer’s identifier, will retrieve only this specific transfer.
• inviteId set to an invite’s identifier, will retrieve only transfers that originate from this invite.
• fileId set to a file’s identifier, will retrieve only transfers that contain this file.
• box knows three valid values : OUTBOX (default) for sent transfers, INBOX for received transfers or REVIEWBOX. The latter is only valid for Company Administrators.

<record>
<id>de00e1b6-06ec-4c72-8be8-b86a5188d61e</id>
<subject>Important File</subject>
<sourceInvite></sourceInvite>
<message>See attached.</message>
<sendAs>some.one@mailinator.com</sendAs>
<creator>some.one@mailinator.com</creator>
<editable>false</editable>
<downloadable>true</downloadable>
<hasErrors>false</hasErrors>
<originator>some.one@mailinator.com</originator>
<recipients>some.body@mailinator.com</recipients>
<completion>0%</completion>
<creationDate>2010-06-01T05:49:19</creationDate>
<deliveryDate>2010-06-01T05:49:19</deliveryDate>
<expiryDate>2010-12-24T16:00:00</expiryDate>
<transferStatus>ACTIVE</transferStatus>
<onHold>false</onHold>
<signed>false</signed>
</record>

If transferStatus is set to UNDERREVIEW, Company Administrators may set it to REVIEWED or REJECTED to respectively allow or block the transfer.

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID			Req	Req
transferId	UUID	Opt
inviteId	UUID	Opt
fileId	UUID	Opti
box	Enum "OUTBOX" (default), "INBOX" or "REVIEWBOX"	Opt
subject	String		Req
sourceInvite	String
message	String		Req
sendAs	Email Address		Opt
creator (not editable)	Email Address			Req
editable	Boolean
downloadable	Boolean
hasErrors	Boolean
originator (not editable)	Email Address			Req
recipients	List of Email Address		Req
completion	Percentage
creationDate	Data
deliveryDate	Data		Req
expiryDate	Data		Req	Req
transferStatus	Enum "UNDERREVIEW", "ACTIVE", "ONHOLD", "EXPIRED" or "TOBESIGNED"			Opt
onHold	Boolean			Req
signed	Boolean		Opt
passwordRequired	Boolean		Opt
files	List of UUIDs		Req

Recipients

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

tip

All requests must include a transferId element, set to the identifier of a transfer or invite the desired recipient(s) relate(s) to. Fetch requests may include the filter element recipientId; set to a recipient’s identifier, it will retrieve only this specific recipient. Alternatively, emailAddress may be set to a specific recipient’s email address.

<record>
<id>4aa30a22-21c2-4e71-a0e1-5bc2e615ef29</id>
<transferId>de00e1b6-06ec-4c72-8be8-b86a5188d61e</transferId>
<owner>false</owner>
<userName>some.one@mailinator.com</userName>
<realName>Some One</realName>
<emailAddress>some.one@mailinator.com</emailAddress>
<limited>false</limited>
<uniqueLink>
https://localhost/cgi-bin/login.fcgi?
link=1e007c36-f94f-4de9-b575-16c0c676b0a0
</uniqueLink>
<remote>false</remote>
<passwordRequired>true</passwordRequired>
<lastLoginDate>2010-11-02T09:29:24</lastLoginDate>
<maxCount>15</maxCount>
<readOnly>false</readOnly>
<doNotNotify>false</doNotNotify>
<complete>false</complete>
<visitedLink>false</visitedLink>
<subscribed>true</subscribed>
<lastNotificationDate>2019-03-05T14:14:39</lastNotificationDate>
<hasNextNotification>false</hasNextNotification>
<nextNotificationDate>2019-03-05T14:14:39</nextNotificationDate>
<nextNotificationTime>2019-03-05T14:14:39</nextNotificationTime>
<scope>TO</scope>
</record>

Only maxCount may be modified. Sending the option remindRecipient with value true will send a reminder email to the recipient.

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID		N/A	Req	Req
transferId (not editable)	UUID	Req		Req
userName	String
realName	String
emailAddress	Email Address
limited	Boolean
uniqueLink	String
remote	Boolean
passwordRequired	Boolean
lastloginDate	Date
maxCount	Unsigned integer			Opt
readOnly	Boolean			Opt
doNotNotify	Boolean			Opt
complete	Boolean
subscribed	Boolean
lastNotificationDate	Date
hasNextNotification	Boolean			Opt
nextNotificationDate	Date			Opt
nextNotificationTime	Date			Opt
scope	String
remind Recipients	Boolean			Opt
owner	Boolean			Opt

Files

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

tip

Fetch requests may include the filter element fileId; set to a file’s identifier, it will retrieve only this specific file.

<record>
<id>1213495b-ca68-4d84-a175-741bce2a9c5a</id>
<transferId>9c06845c-eec4-4c4f-a2dc-54037580592b</transferId>
<name>Qiata_Introduction_8Apr10_rev3.ppt</name>
<size>2.7Mb</size>
<type>OLE2 compound document storage</type>
<nature>UPLOAD</nature>
<checkSum>
5efebbe492279f14368d0312f94f422c405f0fdcd3a0a15476eff6723a65bf4e
</checkSum>
<virusFree>true</virusFree>
<downloadCount>2</downloadCount>
<downloadLink>
/cgi-bin/downloads.cgi?id=1213495b-ca68-4d84-a175-741bce2a9c5a&amp;
transferId=9c06845c-eec4-4c4f-a2dc-54037580592b
</downloadLink>
</record>

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID		Reponse only	Req	N/A
fileId	UUID	Opt
transferId	UUID	Req
name (not editable)	String		Req	Req
size	Size as string, eg "1kb", "1Gb"		Required in bytes, eg "1024b"
nature	Enum "UPLOAD", "ARCHIVE" or "SIGNATURE"
checkSum	String
virusFree	Boolean
downloadCount	Unsigned Integer
downloadLink	Link
startOffset	Unsigned Integer		Req	Req
endOffset	Unsigned Integer		Req	Req
encoding	Enum "NONE" (default) or "BASE64"		Req	Req
content	String		Req	Req

Downloads

Fetch	Update	Add	Remove
Yes	No	No	No

tip

All requests must include a transferId element and a fileId element

<record>
<id>2e3fcd52-fe17-45fa-b5e8-0373b5263731</id>
<transferId>9c06845c-eec4-4c4f-a2dc-54037580592b</transferId>
<fileId>1213495b-ca68-4d84-a175-741bce2a9c5a</fileId>
<fileName>Qiata_Introduction_8Apr10_rev3.ppt</fileName>
<downloader>some.body@mailinator.com</downloader>
<address>192.168.1.33</address>
<port>56454</port>
<method>HTTP_GET</method>
<downloadDate>2010-04-08T09:56:54</downloadDate>
<percentage>100%</percentage>
<duration>31</duration>
</record>

Keyword	Type	Fetch	Add	Update	Remove
id	UUID		N/A	N/A	N/A
transferId	UUID	Req
fileId	UUID	Req
fileName	String
downloader	String
address	String
port	Unsigned integer
method	Enum "HTTP_GET" or "UDT_RECEIVE"
downloadDate	Date
percentage	Percentage
duration (in seconds)	Unsigned integer

Uploads

Fetch	Update	Add	Remove
Yes	No	No	No

tip

All requests must include a fileId element. A userId element may be set to restrict to a specific user.

<record>
<id>33d7c7a7-dcf8-4a4d-97bf-b1a8e260ebd6</id>
<fileId>879b92d4-0746-418d-a08a-977603845bec</fileId>
<uploader>some.body@mailinator.com</uploader>
<address>127.0.0.1</address>
<port>52074</port>
<method>XML_POST</method>
<uploadDate>2010-11-23T10:02:23</uploadDate>
<percentage>100%</percentage>
<startOffset>0</startOffset>
<endOffset>59295</endOffset>
<duration>0</duration>
</record>

Keyword	Type	Fetch	Add	Update	Remove
id	UUID		N/A	N/A	N/A
fileId	UUID	Req
userId	UUID	Req
uploader	String
address	String
port	Unsigned integer
method	Enum "HTTP_POST", "UDT_SEND" or "XML_POST"
uploadDate	Date
percentage	Percentage
startOffset	Unsigned integer
endOffset	Unsigned integer
duration (in seconds)	Unsigned integer

Contacts

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

Fetch requests may include one of these filter elements :

• displayField Searchstring for displayField
• displayName Searchstring for displayName
• emailAddress Searchstring for emailAddress
• textMatchStyle can be substring or startsWith, depending if the match can be found in the middle of the strings or just at the beginning.

tip

To fetch all contacts of a contactlist you need to include the contactListId element. The contactListId 0-USER-CONTACTS is the default contactlist of every user.

Fetch

Example request

<request>
<dataType>contacts</dataType>
<operationType>fetch</operationType>
<data>
<contactListId>0cfd6495-2f14-4589-8c92-7a003a0be616</contactListId>
</data>
<endRow>10</endRow>
</request>

Example response

Each fetched contact is in its own record block.

<response>
<status>0</status>
<startRow>0</startRow>
<endRow>2</endRow>
<totalRows>2</totalRows>
<data>
<record>
<id>14298cbc-7aa7-4bdb-b953-7d83e6f0fb00</id>
<contactListId>7f0e1d9c-87ad-4c5b-967b-f67489f6ab71</contactListId>
<salutation>Mr</salutation>
<firstName>John</firstName>
<lastName>Doe</lastName>
<displayName>John Doe</displayName>
<emailAddress>doe@secudos.com</emailAddress>
<contactType>USER</contactType>
<editable>true</editable>
<unsubscribed/>
</record>
<record>
...
</record>
</data>
</response>

Add

Example request

Multiple contacts needs to be in the format "DISPLAYNAME" <EMAILADDRESS> "DISPLAYNAME2" <EMAILADDRESS2>

<request>
<dataType>contacts</dataType>
<operationType>add</operationType>
<data>
<contactListId>0-USER-CONTACTS</contactListId>
<displayNames>"Max Mustermann" &lt;mustermann@secudos.com&gt; "John Doe" &lt;doe@secudos.com&gt;</displayNames>
</data>
</request>

Example response

Each added contact is in its own record block.

<response>
<status>0</status>
<data>
<record>
<id>f02584aa-a0a7-4815-8bd5-f5e1d05549f0</id>
<contactListId/>
<salutation/>
<firstName/>
<lastName/>
<displayName>Max Mustermann</displayName>
<emailAddress>mustermann@secudos.com</emailAddress>
<contactType>USER</contactType>
<editable>true</editable>
<unsubscribed>false</unsubscribed>
</record>
<record>
...
</record>
</data>
<failureCount>0</failureCount>
<existingCount>0</existingCount>
<newCount>1</newCount>
</response>

Update

Example request

<request>
<dataType>contacts</dataType>
<operationType>update</operationType>
<data>
<id>cd854952-d80a-4319-ad65-08a715c84381</id>
<contactListId>0-USER-CONTACTS</contactListId>
<salutation>Mrs</salutation>
<firstName>Cecile</firstName>
<lastName>Ulphia</lastName>
<displayName>Cecile Ulphia</displayName>
<emailAddress>cecile.ulphia@gmail.com</emailAddress>
<contactType>USER</contactType>
<editable>true</editable>
</data>
</request>

Example response

<response>
<status>0</status>
<data>
<record>
<id>cd854952-d80a-4319-ad65-08a715c84381</id>
<contactListId>0-USER-CONTACTS</contactListId>
<salutation>Mrs</salutation>
<firstName>Cecile</firstName>
<lastName>Ulphia</lastName>
<displayName>Cecile Ulphia</displayName>
<emailAddress>cecile.ulphia@gmail.com</emailAddress>
<contactType>USER</contactType>
<editable>true</editable>
<unsubscribed></unsubscribed>
</record>
</data>
</response>

Remove

Example request

<request>
<dataType>contacts</dataType>
<operationType>remove</operationType>
<data>
<id>cd854952-d80a-4319-ad65-08a715c84381</id>
<contactListId>0-USER-CONTACTS</contactListId>
</data>
</request>

Example response

<response>
<status>0</status>
<data>
<record>
<id>cd854952-d80a-4319-ad65-08a715c84381</id>
</record>
</data>
</response>

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID	Response only	Response only	Req	Req
contactListId	Contact ListID	Opt	Req	Opt	Req
salution	String	Response only	Response only	Opt	N/A
firstName	String	Response only	Response only	Opt	N/A
lastName	String	Response only	Response only	Opt	N/A
displayNames	String	N/A	Required in format "DISPLAYNAME" <MAILADDRESS> Multiple lines for multiple contacts.	N/A	N/A
displayName	String	Optional Only to filter	Response only	Opt	N/A
emailAddress	String	Optional Only to filter	Response only	Req	N/A
contactType	String	Response only	Response only	Response only	N/A
editable	Boolean	Response only	Response only	Response only	N/A
unsubscribed	String	Response only	Response only	Response only	N/A
displayField	String	Optional Only to filter	N/A	N/A	N/A

Contact lists

Fetch	Update	Add	Remove
Yes	Yes	Yes	Yes

Fetch

Example request

<request>
<dataType>contactLists</dataType>
<operationType>fetch</operationType>
<data/>
</request>

Example response

Each fetched contactlist is in its own record block.

<response>
<status>0</status>
<startRow>0</startRow>
<endRow>15</endRow>
<totalRows>15</totalRows>
<data>
<record>
<id>0-USER-CONTACTS</id>
<contactListName>Personal contacts</contactListName>
<editable>false</editable>
<contactID/>
<selectContactList/>
<shareMode>NONE</shareMode>
</record>
<record>
...
</record>

Add

Example request

<request>
<dataType>contactLists</dataType>
<operationType>add</operationType>
<data>
<contactListName>Sales</contactListName>
<shareMode>NONE</shareMode>
</data>
</request>

Example response

<response>
<status>0</status>
<data>
<record>
<id>bdadb250-62a1-4435-8a86-a19a4b0f9f78</id>
<contactListName>Sales</contactListName>
<editable>true</editable>
<shareMode>NONE</shareMode>
</record>
</data>
</response>

Update

Example request

If you want to change the membership of a contact the element contactId and selectContactList are needed. To add a contact to the list selectContactList is true. To remove a contact selectContactList is false.

<request>
<dataType>contactLists</dataType>
<operationType>update</operationType>
<data>
<id>bdadb250-62a1-4435-8a86-a19a4b0f9f78</id>
<contactListName>Sales</contactListName>
<editable>true</editable>
<shareMode>GROUP</shareMode>
<contactId/>
<selectContactList/>
</data>
</request>

Example response

If a contact membership was changed the elements contactId and selectContactList are responded.

<response>
<status>0</status>
<data>
<record>
<id>bdadb250-62a1-4435-8a86-a19a4b0f9f78</id>
<contactListName>Sales</contactListName>
<editable>true</editable>
<shareMode>GROUP</shareMode>
</record>
</data>
</response>

Remove

Example request

<request>
<dataType>contactLists</dataType>
<operationType>remove</operationType>
<data>
<id>bdadb250-62a1-4435-8a86-a19a4b0f9f78</id>
</data>
</request>

Example response

<response>
<status>0</status>
<data>
<record>
<id>bdadb250-62a1-4435-8a86-a19a4b0f9f78</id>
</record>
</data>
</response>

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID	Response only	Response only	Req	Req
contactId	ContactID	Response only	N/A	Required only with selectContactList	N/A
contactListName	String	Response only	Req	Opt	N/A
editable	Boolean	Response only	Response only	Response only	N/A
shareMode	String	Response only	Required only "NONE", "GROUP" or "COMPANY"	Opt	N/A
selectContactList	Boolean	Response only	N/A	Required only with contactId	N/A

Contact import (CSV)

Fetch	Update	Add	Remove	Import
No	No	No	No	Yes

tip

The separator needs to be the same as in the file content. The contactListId requires that this contactlist already exists. The header needs to include these values:

• EMAILADDRESS
• DISPLAYNAME
• TITLE
• LASTNAME
• FIRSTNAME

Example request

<request>
<dataType>contactcsvimport</dataType>
<operationType>import</operationType>
<data>
<contactListId>0-USER-CONTACTS</contactListId>
<separator>,</separator>
<file>
EMAILADDRESS,DISPLAYNAME,TITLE,LASTNAME,FIRSTNAME
"claudina.judye@gmail.com","claudina judye","Mrs","Judye","Claudina"
"maisey.madelene@gmail.com","maisey madelene","Mrs","Madelene","Maisey"
</file>
</data>
</request>

Example response

<response>
<status>0</status>
<data>
<record>
<contactListId>0-USER-CONTACTS</contactListId>
</record>
</data>
</response>

Keyword	Type	Fetch	Add	Update	Remove	Import
contactListId	UUID	N/A	N/A	N/A	N/A	Req
file	string	N/A	N/A	N/A	N/A	Req
separator	String	N/A	N/A	N/A	N/A	Req

Users password

Only users with type LOCAL are allowed to change their passwords. The Update requests requires to input the current password. newPassword and newPasswordAgain have to be identical. The new password must satisfy current company password rules.

note

Azure/ADFS Users passwords are not managed on Qiata.

Fetch	Update	Add	Remove
Yes	Yes	No	No

<response>
    <status>0</status>
    <startRow>0</startRow>
    <endRow>1</endRow>
    <totalRows>1</totalRows><data>
        <record>
            <id>75982e15-da9d-44e7-9614-1b48707cefde</id>
            <userName>dummy@example.com</userName>
        </record>
    </data>
</response>

Keyword	Type	Fetch	Add	Update	Remove
id (not editable)	UUID	req
password	String			req
newPassword	String			req
newPasswordAgain	String			req

Comments

With preview set to true on fetch requests, the comments get striped of any signatures starting with -- and the comments will be decoded first.

note

You cannot comment on Transfers from disabled User.

Fetch	Update	Add	Remove
Yes	Yes	No	No

<response>
    <status>0</status>
    <startRow>0</startRow>
    <endRow>1</endRow>
    <totalRows>1</totalRows><data>
        <record>
            <id>439f8141-8dec-4e91-b726-97d78741dfae</id>
            <objectId>1b4c30fa-85f0-40d5-9ad0-0898317dab75</objectId>
            <objectType>TRANSFER</objectType>
            <subObjectId></subObjectId>
            <subObjectValue></subObjectValue>
            <commenter>dummy@example.com</commenter>
            <target></target>
            <comment>
                <![CDATA[Dear recipient, here are the files.]]>
            </comment>
            <commentType>TEXT</commentType>
            <commentDate>2022-07-29T06:26:10</commentDate>
            <scope>PUBLIC</scope>
            <onCreation>false</onCreation>
            <removable>true</removable>
        </record>
    </data>
</response>

Keyword	Type	Fetch	Add	Update
id	UUID	req
objectId	String or Empty to reference transfer comments	opt	opt	req
objectType	Enum 'GROUP', 'TRANSFERFILE', 'COMPANY'	opt	opt	req
originalMessage	Boolean String 'true', 'false'	opt		req
preview	Boolean String 'true', 'false'	opt
comment	String		req
commenter	String email address
target	String email address
commentDate	String Date e.g.: 2022-07-29T06:26:10
onCreation	Boolean String 'true', 'false'
scope	String Enum 'PUBLIC', 'AUDITMESSAGE', 'AUDITNOTE'		req
removable	Boolean String

Message templates

On fetch you can request a specific template, by passing the templateID. If templateID is part of the fetch request, you may also set preview to get its content.

Fetch	Update	Add	Remove
Yes	No	Yes	No

<response>
    <status>0</status>
    <startRow>0</startRow>
    <endRow>2</endRow>
    <totalRows>2</totalRows><data>
        <record>
            <id>0-DEFAULT-STYLE</id>
            <templateName>Voreingestellt</templateName>
            <templateType>EMAIL</templateType>
            <templateStyle>TRANSFER</templateStyle>
            <templateContent>
                <![CDATA[]]>
            </templateContent>
        </record>
        <record>
            <id>bb5624c9-01ca-4195-83e1-39f0e5dc4355</id>
            <templateName>Billings</templateName>
            <templateType>EMAIL</templateType>
            <templateStyle>TRANSFER</templateStyle>
            <templateContent>
                <![CDATA[...]]>
            </templateContent>
        </record>
    </data>
</response>

Keyword	Type	Fetch	Add	Update
id	UUID	req
templateId	UUID	opt
templateStyle	String		opt(only if you can SendNewsletter)
templateType	String Enum 'HTML', 'TEXT'		req
preview	Boolean String
templateContent	String	res	req
templateName	String	res	req

Users PersonalSpace password

Fetch	Update	Add	Remove
Yes	Yes	No	No

<response>
    <status>0</status>
    <startRow>0</startRow>
    <endRow>1</endRow>
    <totalRows>1</totalRows><data>
        <record>
            <id>52705717-94fc-4bb5-9a92-341aac0cf522</id>
            <userName>dummy@example.com</userName>
            <multiSpacePath>https://demo.secudos.com/space</multiSpacePath>
            <authType>digest</authType>
        </record>
    </data>
</response>

Keyword	Type	Fetch	Update
id	UUID	req	req
userName	String email address	req	req
multiSpacePath	String	res	opt
authType	String eg. 'digest'	res	req
newPassword	String		req
newPasswordAgain	String		req

UI Theme

Fetch current company colors. Fetch branding states for logos.

Fetch	Update	Add	Remove
Yes	No	No	No

<response>
    <status>0</status><data>
        <record>
            <id>UITHEME-0</id>
            <themecolor> red;</themecolor>
            <themecoloralt> #2775a9;</themecoloralt>
            <logincolor> linear-gradient( to bottom, #79aed5E6 0%, #000000B3 100% );</logincolor>
            <topbar> #2f8ecd;</topbar>
            <sidebartop> #2f8ecd;</sidebartop>
            <background>modified</background>
            <logoint>notmodified</logoint>
            <logologin>notmodified</logologin>
        </record>
    </data>
</response>

Keyword	Type	Fetch
id	UUID	res
themecolor	String Color	res
themecoloralt	String Color	res
topbar	String Color	res
logincolor	String Background/Color	res
background	String Enum 'notmodified', 'modified'	res
logoint	String Enum 'notmodified', 'modified'	res
logologin String Enum 'notmodified', modified'	String Enum 'notmodified', 'modified'	res

TeamTransfers

The below activities are supported under Team Transfer:

1. Fetch existing Team Transfer for a given user
2. Fetch root (top level) folders for a given Team Transfer
3. Fetch subfolders for a given folder
4. Upload files
5. Update Team Transfer after uploading files

User cookie is required for all Team Transfer activities. In order to get user cookie one has to login. Refer Logging in and out for how to login.

After Team Transfer activities are completed one has to logout in order to release session. Refer Logging in and out for how to logout.

Fetch existing Team Transfers

Keyword	Type	Fetch	Add	Update	Remove
User cookie		Req
box		Req
startRow		Req
endRow		Req
textMatchStyle		Req
sortBy		Req

Request

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>transfers</dataType>
<operationType>fetch</operationType>
<data>
<box>TEAMTRANSFERSBOX</box>
</data>
<startRow>0</startRow>
<endRow>75</endRow>
<textMatchStyle>exact</textMatchStyle>
<sortBy>-creationDate</sortBy>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>0</status>
<startRow>0</startRow>
<endRow>1</endRow>
<totalRows>1</totalRows>
<data>
<record>
<id>ce76f9d4-ee1d-4b47-8fae-4cc0e25094a7</id>
<subject>Teamwork</subject>
<sourceInvite></sourceInvite>
<message></message>
<sendAs></sendAs>
<creator>creator@example.com</creator>
<editable>true</editable>
<appendable>true</appendable>
<removable>true</removable>
<downloadable>true</downloadable>
<hasErrors>false</hasErrors>
<originator>originator@example.com</originator>
<recipients>recipient@example.com</recipients>
<completion>0</completion>
<creationDate>2015-01-07T15:22:07</creationDate>
<deliveryDate>2015-01-07T15:22:07</deliveryDate>
<expiryDate>2015-02-06T15:59:59</expiryDate>
<transferStatus>ACTIVE</transferStatus>
<onHold>false</onHold>
<signed>false</signed>
<archiveId></archiveId>
<subType>TEAMTRANSFER</subType>
</record>
</data>
</response>

tip

transferStatus: Possible status are ACTIVE and EXPIRED. Id: Team Transfer id

Fetch root (or top level) folders

Keyword	Type	Fetch	Add	Update	Remove
User cookie		Req
box		Req
transferId		Req
startRow		Req
endRow		Req

Request

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>transfers</dataType>
<operationType>fetch</operationType>
<data>
<box>FOLDERSBOX</box>
<transferId>yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy</transferId>
</data>
<startRow>0</startRow>
<endRow>75</endRow>
</request>

tip

yyy: transferId This returns just the folder in root folder. Files must be fetched using the normal files-fetch request and the transferId.

Response

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>0</status>
<startRow>0</startRow>
<endRow>3</endRow>
<totalRows>3</totalRows>
<data>
<record>
<id>16222db9-12b2-4fc6-9f6e-cb37706e8f24</id>
<name>folder name 1</name>
</record>
<record>
<id>f01eee52-300f-4b7c-b6ac-ce8f012dd4f7</id>
<name> folder name 2</name>
</record>
<record>
<id>61d99d80-d29b-443a-8519-0e78575b531d</id>
<name> folder name 3</name>
</record>
</data>
</response>

Fetch subfolders in folder

Keyword	Type	Fetch	Add	Update	Remove
Cookie		Req
box		Req
folderId		Req
startRow		Req
endRow		Req

Request

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>transfers</dataType>
<operationType>fetch</operationType>
<startRow>0</startRow>
<endRow>75</endRow>
<data>
<box>SUBFOLDERS</box>
<folderId>zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz</folderId>
</data>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>0</status>
<startRow>0</startRow>
<endRow>1</endRow>
<totalRows>1</totalRows>
<data>
<record>
<id>zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz</id>
<name>folder name 1</name>
</record>
</data>
</response>

tip

If there are more than 75 Team Transfers then please submit another request with startRow 75 and endRow 150. zzz: id

Upload file

Keyword	Type	Fetch	Add	Update	Remove
Cookie			Req
id			Req
name			Req
size			Req
startOffset			Req
endOffset			Req
encoding			Req
path

Request

<Next line is boundary>
------fd0d4b854d3a447d9de824fafc3a2704--
Content-Disposition: form-data;name="request"; filename="testDoc.xml"
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>files</dataType>
<operationType>add</operationType>
<data>
<id>team transfer id</id>
<name>file name</name>
<size>file size</size>
<startOffset>0</startOffset>
<endOffset>size of file in bytes -1 </endOffset>
<encoding>BASE64</encoding>
<path>Not required. Just keep blank</path>
</data>
</request>
<Next line is boundary>
------fd0d4b854d3a447d9de824fafc3a2704--
Content-Disposition: form-data;name="myFile";
filename="New Text Document.txt
"Content-Type: .txt
<add actual file content here>
<Next line is boundary>
------fd0d4b854d3a447d9de824fafc3a2704--
Encoding: Either NONE or BASE64

Response

<?xml version="1.0" encoding="utf-8"?>
<response><status>0</status>
<data>
<record>
<id>xxxxxxxx-xxxx-xxxxx-xxxxxxxxx</id>
<transferId></transferId>
<name>file name</name>
<path></path>
<size>16B </size>
<type>Unknown</type>
<nature>UPLOAD</nature>
<checkSum></checkSum>
<hasVirus>false</hasVirus>
<removable>true</removable>
<version>0</version>
<archiveId></archiveId>
<keyId></keyId>
<downloadCount>0</downloadCount>
<downloadLink>/cgi-bin/downloads.cgi?id=c89c7272-0107-
43a8-906b-fee1bfde22d2&amp;no-gzip</downloadLink>
</record>
</data>
</response>

tip

xxx: file Id. Use this in ’update Team Transfer’

Add to TeamTransfer

Keyword	Type	Fetch	Add	Update	Remove
Cookie		Req
subject
message
toRecipients		Req
ccRecipients		Req
bccRecipients		Req
deliveryDate		Req
expiryDate		Req
files		Req
filePaths		Req
sameLink		Req
teamTransferId		Req
checkTransferLimits		Req
notifyRecipients		Req

Request

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>transfers</dataType>
<operationType>add</operationType>
<data>
<subject>
outlook version 2.1.6.0 is ready for release test
</subject>
<message>
<![CDATA[message. Is not used. But fill in something]]>
</message>
<toRecipients></toRecipients>
<ccRecipients></ccRecipients>
<bccRecipients></bccRecipients>
<deliveryDate>14 January 2015</deliveryDate>
<expiryDate>2015-01-14T17:35:59</expiryDate>
<files>xxxxxxxx-xxxx-xxxxx-xxxxxxxxx</files>
<filePaths>path, where to put file in team transfer</filePaths>
<sameLink>true</sameLink>
<teamTransferId>
yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
</teamTransferId>
<checkTransferLimits>false</checkTransferLimits>
<notifyRecipients>false</notifyRecipients>
</data>
</request>

tip

If there are more than one file uploaded and you want to update Team Transfer in one shot then add , (comma) between files ids in files tag. For each file you added, you must specify the filePaths in filePaths tag, seperated by |(pipe) symbol. If files are to be added to root folder then keep empty space for the corresponding file id. The path is where to store the file in Team Transfer. xxx: file Id yyy: teamTransferId

Response

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>0</status>
<data>
<record>
<id>1777caa7-c629-46b8-a408-e4a2cd7d431d</id>
<subject>test</subject>
<sourceInvite></sourceInvite>
<creator>creator@exmaple.com</creator>
<editable>true</editable>
<downloadable>true</downloadable>
<originator>originator@example.com</originator>
<recipients></recipients>
<completion>0%</completion>
<creationDate>2015-01-14T22:35:26</creationDate>
<deliveryDate>2015-01-14T22:35:26</deliveryDate>
<expiryDate>2015-01-14T22:35:26</expiryDate>
<transferStatus>checked</transferStatus>
<onHold>false</onHold>
<signed>false</signed>
<archiveId/>
<newsletter>false</newsletter>
</record>
</data>
</response>

Examples

Sending a new file for simple transfer

Before a file can be added to a transfer and sent to anyone, it must be fully uploaded to the system. Uploads are performed with one Add operation followed by as many Update operations as necessary. Content can thus be incrementally uploaded. Several options are available for content. It may be:

• sent inline as-is in a content element with encoding set to NONE. CDATA may be used. The API developer must of course make sure the resulting XML document is valid, and keep in mind that newlines will be ignored.
• encoded in base64 and sent inline in a content element with encoding set to BASE64. It is recommended that encoded lines wrap after 76 characters. CDATA may be used.
• sent out-of-band in a multipart form (Content-Type set to ”multipart/form-data”). In this case, the XML document must be the first part, the file content coming second. The encoding element is set to NONE, and no content element is specified.

The first two options are only suitable to small and medium-sized chunks. The API will return a ”Request too large” error if chunks should be taken out of the XML and uploaded out-of-band. In all cases, startOffset and endOffset must specify where the attached content starts and finishes in the final file. Note that content may only be sent incrementally, and each Update operation must have a startOffset that’s equal to the previous operation’s endOffset plus one.

If the data was base64 encoded, these offsets apply to the raw base64-decoded data. For instance, one could send the following to create a new file:

Request

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>files</dataType>
<operationType>add</operationType>
<data>
<name>HelloWorld.txt</name>
<size>26b</size>
<startOffset>0</startOffset>
<endOffset>10</endOffset>
<encoding>NONE</encoding>
<content>Hello World</content>
</data>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response>
<status>0</status>
<data>
<record>
<id>55ac1bf4-172e-4df1-9bdb-7e8171234598</id>
<transferId></transferId>
<name>HelloWorld.txt</name>
<size>26b</size>
<type>Unknown</type>
<nature>UPLOAD</nature>
<virusFree>true</virusFree>
<downloadCount>0</downloadCount>
<downloadLink>
/cgi-bin/downloads.cgi?id=55ac1bf4-172e-4df1-9bdb-7e8171234598
</downloadLink>
</record>
</data>
</response>

The file identifier provided in the response must be quoted in all further operations together with the original name. For example, the remaining content may be sent with:

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>files</dataType>
<operationType>update</operationType>
<data>
<id>55ac1bf4-172e-4df1-9bdb-7e8171234598</id>
<name>HelloWorld.txt</name>
<startOffset>11</startOffset>
<endOffset>25</endOffset>
<encoding>BASE64</encoding>
<content>CkhvdyBpcyBsaWZlID8K</content>
</data>
</request>

Now that the file has been fully uploaded, it may be added to a new transfer:

<?xml version="1.0" encoding="utf-8"?>
<request>
<dataType>transfers</dataType>
<operationType>add</operationType>
<data>
<subject>Hello World</subject>
<message>See attached.</message>
<recipients>some.body@mailinator.com</recipients>
<files>55ac1bf4-172e-4df1-9bdb-7e8171234598</files>
<expiryDate>2010-12-24T16:00:00</expiryDate>
<signed>false</signed>
</data>
</request>

Logging in and out (DEPRECATED)

danger

Logging in and out has been replaced by our new V2 interface. You can find instructions for this at API-LOGIN-V2

Username and password must be sent to /cgi-bin/login.fcgi with a HTTP POST. Contents must be URL-encoded and Content-Type set to application/x-www-form-urlencoded. For instance:

username=some.body@mailinator.com&password=mypassword

In response, login-fcgi will set a FTAUser cookie. That is the cookie that must be specified in every request. The rest of the response can be safely ignored.

When done, a logout can be achieved with a HTTP GET to /cgi-bin/login.fcgi?mode=logout FTAUser should of course be specified at this point too. Once a logout has been performed, the FTAUser cookie becomes invalid and can be discarded.

You can also enable short response for the login request. In case you don’t need the WebUI content. The flag can be added to the login HTML POST optionally.

Values are:

xmlLogin=true (short response)
xmlLogin=false (long response / WebUI)

username=some.body@mailinator.com&password=mypassword&xmlLogin=true

Private extensions

When adding a transfer, the following elements may be added to the record block:

Keyword	Type	Fetch	Add	Update	Remove
sameLink	Boolean	N/A		N/A	N/A
notifyRecipients	Boolean	N/A		N/A	N/A

When set to true, the sameLink element directs the Qiata to generate one link shared by all recipients of the transfer. This link will prompt recipients for their email address. notifyRecipients on the other hand turns off email notifications to recipients when set to false. It is assumed the caller will notify recipients on its own.