Skip to main content

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

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

FetchUpdateAddRemove
YesYesYesYes

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.

KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDReqReq
groupIdUUIDOpt
memberIdUUIDOpt
groupNameStringReqReq
hierarchyStringOptOpt
canInviteBooleanReqReq
canSignBooleanReqReq
canSendNewslettersBooleanReqReq
canSendTeamTransfersBooleanReqReq
canSendAsBooleanReqReq
sendAsAddressesList of stringsReqReq
teamMemberAddressesList of stringsReqReq
storagequota UnittestEnum "GBYTE", "MBYTE" or "KBYTE"OptlOpt
storageQuotaUnsigned integerOptOpt
userStorageQuotaUnit userStorageQuotaGBYTE|MBYTE|KBYTE, Unsigned integerOptlOpt
usedStorageMB (in Megabytes)Unsigned integerOptOpt
usedStorageSize as string
authServerUUIDOptOpt
transfersCountUnsigned integerOptOpt
accessRangesList of IPv4 addresses/rangesOptOpt
hasAccess-RangesBooleanOptOpt
positiveSignUp-RulesList of patternsOptOpt
negativeSignUp RulesList of patternsOptOpt
hasSignUpRulesBooleanOptlOpt
externalOnlyBooleanOptlOpt
closeToLimitsBooleanOptlOpt

Users

FetchUpdateAddRemove
YesYesYesYes

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>
KeywordTypeFetchAddUpdateRemove
idUUIDReqReq
userNameStringOptReq
realNameStringOpt
emailAddressStringReqReq
authTypeEnum LOCAL|LDAPReq
roleEnum LIMITED|USER|AUDITOROptReqReq
groupNameStringOptOpt
assignedGroupNameString
lastLoginDateDate
secondLastLoginDateDate
firstLoginBoolean
isLoggedInBoolean
hasSessionBoolean
sessionDelayInteger
lastPasswordChangeDateDate
disabledUserBooleanOptOptOpt
disabledUserReasonStringOptOptOpt
readOnlyBoolean
setPasswordBooleanOpt
newPasswordStringOpt
newPasswordAgainStringOpt
storageQuotaUnitStringOptReqOpt
storageQuotaIntegerOptReqOpt
hasExpiryDateBooleanReqReq
expiryDateDateOptOpt
transfersCountInteger
transferFilesSizeSize as string
savedStorageSizeSize as string
archiveFilesSizeSize as string
deletedFileSizeSize as string
usedStorageMBSize as string
usedStorageSize as string
storageLeftStringSize as string
accessRangesString
hasAccessRangesBoolean
newCountInteger
closeToLimitsBoolean
miscFlagsList
isNoticeBoardEnabledBoolean
noticeBoardMessageString
showUploadManagerWarningBoolean
preferredLanguageStringReq
bccPasswordBooleanOpt
currentUserOnlyBooleanOpt
auditorsOnlyBooleanOpt
userIdStringOpt

Audit entries

FetchUpdateAddRemove
YesNoNoNo

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.
KeywordTypeFetchAddUpdateRemove
idUUIDN/AN/AN/A
idFilterUUIDOpt
typeFilterStringOpt
userFilterUUIDOpt
fileNameFilterStringOpt
fileTypeFilterStringOpt
successFilterEnum "ALL"(default), "FAILURE" or "SUCCESS"Opt
actionTypeString
resultCodeInteger
userIdUUID
userNameString
objectTypeString
objectIdUUID
objectValueString
parentObjectTypeString
parentObjectIdUUID
parentObjectValueString
actionDateDate
formattedValueString
addressIP address
portInteger
removedBoolean

Settings entries

FetchUpdateAddRemove
YesNoYesNo

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>
KeywordTypeFetchAddUpdateRemove
idUUIDReq
objectIdUUIDReq
objectTypeStringReqReq
maxCountUSER|IntegerCR
maxCountIntInteger
maxCountOverrideInteger
daysToExpiryUSER|IntegerCR
daysToExpiryIntInteger
daysToExpiryOverrideInteger
checkPasswordsUSER|YES|NOCR
checkPasswordsOverrideBoolean
confirmNotificationsUSER|YES|NOC1
confirmNotificationsOverrideBoolean
recipientRemindersUSER|YES|NOC1
recipientRemindersOverrideBoolean
recipientNotificationsUSER|YES|NOC1
recipientNotificationsOverrideBoolean
downloadNotificationsUSER|YES|NOC1
downloadNotificationsOverrideBoolean
expiryRemindersUSER|YES|NOC1
expiryRemindersOverrideBoolean
signFilesBooleanCR
uploadAppletUSER|YES|NOC1
downloadAppletYES|NO
isPincodeRequiredUSER|Yes|NoC1
pincodeOverrideBoolean
expiredNotCompletedNotificationsUSER|YES|NOC1
appletsOverrideBoolean
fileNamesStringC1
mobileNumberStringO1
preferredLanguageStringO1
signatureStringO1
uploadSettingsOnlyBooleanOpt
emailSettingsOnlyBooleanOpt
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.

FetchUpdateAddRemove
YesNoNoNo
<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>
KeywordType/ValueFetch
idUUIDreq
objectIdStringreq
objectType"USER"req
newPasswordString
newPasswordAgainString

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

FetchUpdateAddRemove
YesYesYesYes

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.

KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDReqReq
inviteIdUUIDOpt
boxEnum "OUTBOX" (default) "INBOX" or "REVIEWBOX"Opt
subjectStringReq
messageStringReq
creator (not editable)Email AddressReq
editableBoolean
appendableBoolean
removableBoolean
hasErrorsBoolean
recipientsList of Email AddressesReq
ccRecipientsList of Email Addresses
bccRecipientsList of Email Addresses
replyToRecipientsList of Email Addresses
completionPercentage
creationDateDate
deliveryDateDateReq
expiryDateDateReqReq
inviteStatusEnum "UNDERREVIEW", "ACTIVE", "ONHOLD" or "EXPIRED"Opt
onHoldBooleanReq
archiveIdUUIDOpt

Transfers

FetchUpdateAddRemove
YesYesYesYes

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.

KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDReqReq
transferIdUUIDOpt
inviteIdUUIDOpt
fileIdUUIDOpti
boxEnum "OUTBOX" (default), "INBOX" or "REVIEWBOX"Opt
subjectStringReq
sourceInviteString
messageStringReq
sendAsEmail AddressOpt
creator (not editable)Email AddressReq
editableBoolean
downloadableBoolean
hasErrorsBoolean
originator (not editable)Email AddressReq
recipientsList of Email AddressReq
completionPercentage
creationDateData
deliveryDateDataReq
expiryDateDataReqReq
transferStatusEnum "UNDERREVIEW", "ACTIVE", "ONHOLD", "EXPIRED" or "TOBESIGNED"Opt
onHoldBooleanReq
signedBooleanOpt
passwordRequiredBooleanOpt
filesList of UUIDsReq

Recipients

FetchUpdateAddRemove
YesYesYesYes
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.

KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDN/AReqReq
transferId (not editable)UUIDReqReq
userNameString
realNameString
emailAddressEmail Address
limitedBoolean
uniqueLinkString
remoteBoolean
passwordRequiredBoolean
lastloginDateDate
maxCountUnsigned integerOpt
readOnlyBooleanOpt
doNotNotifyBooleanOpt
completeBoolean
subscribedBoolean
lastNotificationDateDate
hasNextNotificationBooleanOpt
nextNotificationDateDateOpt
nextNotificationTimeDateOpt
scopeString
remind RecipientsBooleanOpt
ownerBooleanOpt

Files

FetchUpdateAddRemove
YesYesYesYes
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>
KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDReponse onlyReqN/A
fileIdUUIDOpt
transferIdUUIDReq
name (not editable)StringReqReq
sizeSize as string, eg "1kb", "1Gb"Required in bytes, eg "1024b"
natureEnum "UPLOAD", "ARCHIVE" or "SIGNATURE"
checkSumString
virusFreeBoolean
downloadCountUnsigned Integer
downloadLinkLink
startOffsetUnsigned IntegerReqReq
endOffsetUnsigned IntegerReqReq
encodingEnum "NONE" (default) or "BASE64"ReqReq
contentStringReqReq

Downloads

FetchUpdateAddRemove
YesNoNoNo
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>
KeywordTypeFetchAddUpdateRemove
idUUIDN/AN/AN/A
transferIdUUIDReq
fileIdUUIDReq
fileNameString
downloaderString
addressString
portUnsigned integer
methodEnum "HTTP_GET" or "UDT_RECEIVE"
downloadDateDate
percentagePercentage
duration (in seconds)Unsigned integer

Uploads

FetchUpdateAddRemove
YesNoNoNo
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>
KeywordTypeFetchAddUpdateRemove
idUUIDN/AN/AN/A
fileIdUUIDReq
userIdUUIDReq
uploaderString
addressString
portUnsigned integer
methodEnum "HTTP_POST", "UDT_SEND" or "XML_POST"
uploadDateDate
percentagePercentage
startOffsetUnsigned integer
endOffsetUnsigned integer
duration (in seconds)Unsigned integer

Contacts

FetchUpdateAddRemove
YesYesYesYes

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.

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>
KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDResponse onlyResponse onlyReqReq
contactListIdContact ListIDOptReqOptReq
salutionStringResponse onlyResponse onlyOptN/A
firstNameStringResponse onlyResponse onlyOptN/A
lastNameStringResponse onlyResponse onlyOptN/A
displayNamesStringN/ARequired in format "DISPLAYNAME" <MAILADDRESS> Multiple lines for multiple contacts.N/AN/A
displayNameStringOptional Only to filterResponse onlyOptN/A
emailAddressStringOptional Only to filterResponse onlyReqN/A
contactTypeStringResponse onlyResponse onlyResponse onlyN/A
editableBooleanResponse onlyResponse onlyResponse onlyN/A
unsubscribedStringResponse onlyResponse onlyResponse onlyN/A
displayFieldStringOptional Only to filterN/AN/AN/A

Contact lists

FetchUpdateAddRemove
YesYesYesYes

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>
KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDResponse onlyResponse onlyReqReq
contactIdContactIDResponse onlyN/ARequired only with selectContactListN/A
contactListNameStringResponse onlyReqOptN/A
editableBooleanResponse onlyResponse onlyResponse onlyN/A
shareModeStringResponse onlyRequired only "NONE", "GROUP" or "COMPANY"OptN/A
selectContactListBooleanResponse onlyN/ARequired only with contactIdN/A

Contact import (CSV)

FetchUpdateAddRemoveImport
NoNoNoNoYes
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>
KeywordTypeFetchAddUpdateRemoveImport
contactListIdUUIDN/AN/AN/AN/AReq
filestringN/AN/AN/AN/AReq
separatorStringN/AN/AN/AN/AReq

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.

FetchUpdateAddRemove
YesYesNoNo
<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>
KeywordTypeFetchAddUpdateRemove
id (not editable)UUIDreq
passwordStringreq
newPasswordStringreq
newPasswordAgainStringreq

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.

FetchUpdateAddRemove
YesYesNoNo
<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>
KeywordTypeFetchAddUpdate
idUUIDreq
objectIdString or Empty to reference transfer commentsoptoptreq
objectTypeEnum 'GROUP', 'TRANSFERFILE', 'COMPANY'optoptreq
originalMessageBoolean String 'true', 'false'optreq
previewBoolean String 'true', 'false'opt
commentStringreq
commenterString email address
targetString email address
commentDateString Date e.g.: 2022-07-29T06:26:10
onCreationBoolean String 'true', 'false'
scopeString Enum 'PUBLIC', 'AUDITMESSAGE', 'AUDITNOTE'req
removableBoolean 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.

FetchUpdateAddRemove
YesNoYesNo
<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>
KeywordTypeFetchAddUpdate
idUUIDreq
templateIdUUIDopt
templateStyleStringopt(only if you can SendNewsletter)
templateTypeString Enum 'HTML', 'TEXT'req
previewBoolean String
templateContentStringresreq
templateNameStringresreq

Users PersonalSpace password

FetchUpdateAddRemove
YesYesNoNo
<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>
KeywordTypeFetchUpdate
idUUIDreqreq
userNameString email addressreqreq
multiSpacePathStringresopt
authTypeString eg. 'digest'resreq
newPasswordStringreq
newPasswordAgainStringreq

UI Theme

Fetch current company colors. Fetch branding states for logos.

FetchUpdateAddRemove
YesNoNoNo
<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>
KeywordTypeFetch
idUUIDres
themecolorString Colorres
themecoloraltString Colorres
topbarString Colorres
logincolorString Background/Colorres
backgroundString Enum 'notmodified', 'modified'res
logointString 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

KeywordTypeFetchAddUpdateRemove
User cookieReq
boxReq
startRowReq
endRowReq
textMatchStyleReq
sortByReq

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

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

Fetch root (or top level) folders

KeywordTypeFetchAddUpdateRemove
User cookieReq
boxReq
transferIdReq
startRowReq
endRowReq
<?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.

Fetch subfolders in folder

KeywordTypeFetchAddUpdateRemove
CookieReq
boxReq
folderIdReq
startRowReq
endRowReq
<?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>
tip

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

Upload file

KeywordTypeFetchAddUpdateRemove
CookieReq
idReq
nameReq
sizeReq
startOffsetReq
endOffsetReq
encodingReq
path
<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
tip

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

Add to TeamTransfer

KeywordTypeFetchAddUpdateRemove
CookieReq
subject
message
toRecipientsReq
ccRecipientsReq
bccRecipientsReq
deliveryDateReq
expiryDateReq
filesReq
filePathsReq
sameLinkReq
teamTransferIdReq
checkTransferLimitsReq
notifyRecipientsReq
<?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

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:

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

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:

KeywordTypeFetchAddUpdateRemove
sameLinkBooleanN/AN/AN/A
notifyRecipientsBooleanN/AN/AN/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.