1. Initialize Group Transfer

Description

This API allows a client to initialize a new file upload group session where the file can be grouped and uploaded in chunks.

URL Path

/transfer

Method

GET

When using a diode without GET support

URL Path

/transfer_diode

Method

POST

Permissions Restrictions

Even if the current API method is open to multiple user roles (i.e. Administrator and User), only the Administrator has a full set of permissions.

Administrators can impersonate users, or even other administrators.

For the User role, the permissions apply an even more strict rules set: they can only upload files in their own account - they don't have any impersonation rights.
Although it's not something that applies directly to the current API method, it is worth mentioning that after a transfer has been started (i.e. this method has been called successfully), the other transfer methods (e.g. Init file transfer, Patch file, Complete File, etc.) will only be accessible to the user that has initiated the transfer (the one who's API key was used to make this request). No other user can alter a transfer that's in progress.

HTTP header parameters

Authorization

The API key of the caller

REQUIRED

This header should have the following format:
Bearer [API key obtained from the authenticate API]
Example: Bearer Cp01BwnXAIOLZXxn7yogjKqIZnZpQD

group_id

A unique transfer group id.

OPTIONAL

A unique transfer group id can be transmitted to support Diode scenarios. If no id has been specified MetaDefender Vault will generate a unique id. Must be a valid v4 UUID (RFC4122 standard)

impersonate_as
send_as

A username that you wish to impersonate and send files
on behalf of

OPTIONAL*

Must be a valid user or email address
Note: please use impersonate_as header because send_as will be deprecated

share_with
recipients

A list of usernames or email addresses to share the files with

OPTIONAL*

Must be one or more valid users or email addresses. Separate multiple entries with a comma (,)
Note: please use share_with header because recipients will be deprecated

subject

File Transfer Subject

OPTIONAL

 

message

File Transfer Body Message

OPTIONAL

 

source

Origin of transfer

OPTIONAL

0 = REST (default)
1 = Kiosk
2 = WebUI

expires

Expiry date for transfer group

DEPRECATED

Note: This header has been deprecated please set it using 5. Complete Group Transfer

expires_after

Expiry time span for transfer group

DEPRECATED

Note: This header has been deprecated please set it using 5. Complete Group Transfer

* If send_as or recipients are not specified when making the request, they will be set, by default, to the same value as the request initiator (i.e. the user who's API key has been used to make the request).

Note

The following headers support URL encoding:

  • impersonate_as

  • share_with

  • subject

  • message

Example:

message*=UTF-8''foo-%c3%a4-%e2%82%ac


Request Codes

200

OK

Successful request

400

Bad Request

Invalid HTTP request

401

Invalid parameter

An invalid header parameter was specified.

403

Forbidden

  • Authentication credentials incorrect

  • User role does not permit impersonation

  • Cannot impersonate a user with higher permissions

500

Internal Server Error

Server is temporarily unavailable

Response

Example of a successful scan request:

{
"group_id" : "7640c7dca606418bbd2ba010e4649636"
}

Descriptions of response:

group_id

Group id.

The id of the transfer group.

Limitations

Please always specify the whole time span format (DD:HH:MM:SS), in order to avoid any issues. Due to the way the time span is parsed in C# we end up having the following cases:

- 23:00:00 is parsed to (0 days, 23 hours, 0 minutes and 0 seconds)

- 30:00:00 is parsed to (30 days, 0 hours, 0 minutes and 0 seconds)

TimeSpan.Parse("23:00:00");
{23:00:00}
Days: 0
Hours: 23
Milliseconds: 0
Minutes: 0
Seconds: 0
Ticks: 828000000000
TotalDays: 0.95833333333333326
TotalHours: 23.0
TotalMilliseconds: 82800000.0
TotalMinutes: 1380.0
TotalSeconds: 82800.0
TimeSpan.Parse("30:00:00");
{30.00:00:00}
Days: 30
Hours: 0
Milliseconds: 0
Minutes: 0
Seconds: 0
Ticks: 25920000000000
TotalDays: 30.0
TotalHours: 720.0
TotalMilliseconds: 2592000000.0
TotalMinutes: 43200.0
TotalSeconds: 2592000.0