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 Error
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>
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.
- 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 <some.one@mailinator.com>, Some Body
<some.body@mailinator.com>,... </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 |
- 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>
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 |
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 |
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&
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 |
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 |
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.
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
- Add
- Update
- Remove
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>
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" <mustermann@secudos.com> "John Doe" <doe@secudos.com></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>
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>
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
- Add
- Update
- Remove
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>
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>
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>
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 |
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.
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.
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:
- Fetch existing Team Transfer for a given user
- Fetch root (top level) folders for a given Team Transfer
- Fetch subfolders for a given folder
- Upload files
- 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
- Response
<?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>
<?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>
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
- Response
<?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>
yyy: transferId This returns just the folder in root folder. Files must be fetched using the normal files-fetch request and the transferId.
<?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
- Response
<?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>
<?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>
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
- Response
<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
<?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&no-gzip</downloadLink>
</record>
</data>
</response>
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
- Response
<?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>
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
<?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
- Response
<?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>
<?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)​
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.